Connect an app to Home

connect lets an app keep its existing local accounts and accept Home sign-in after the person explicitly links both identities. The app still decides who may enter and what they may access.

Load optional settings with CredentialsFromEnv("SHEETS"), then validate them with DecodeCredentials(settings, origin) once you know the app's origin. The variables end in _HOME_ISSUER, _HOME_CONSUMER_ID, _HOME_KEYS_BASE64 and _HOME_DEK_BASE64. All empty means disabled; a partial configuration fails. HOME_DIRECTORY_ORIGIN (unprefixed, the name Home itself reads) optionally supplies the hub directory origin as Credentials.Directory, for an app switcher and "All apps" link. It enables nothing on its own and must be a bare https origin. Use a dedicated random 32-byte storage key and a distinct namespace per app. Keep this key stable: it protects proof state and keyed local-person bindings. Replacing it without a migration makes existing links unusable; rotation requires an explicit migration with both keys, which this package does not yet provide.

Apply handoff.Migrations and linkstore.Migrations using your framework's migration package. The latter's namespace is linkstore.SchemaNamespace. This package imports neither framework session nor migration types, so old and new Rastrillo apps can share the same protocol.

Construct Bridge with the hooks in Config. Read the actual session cookie; MintHomeSession stores the opaque Home subject with method HomeMethod and the supplied authentication time. LookupLocalSession reads an existing local account. LookupPerson uses its supplied SQL query object and rechecks current admission; return sql.ErrNoRows for missing or disallowed accounts. Neither hook creates accounts, samples or identity mappings. The returned label must be the canonical verified local address, never an editable display name. Local IDs must never be reused, even for a new account with the same address. Delete the account's home_identity_links rows in the same transaction as the local account. The shared schema cannot impose a foreign key on app-owned tables. A keyed binding detects reuse with a different address at every proof stage and resolution. Address changes require explicit removal and fresh linking; old or unbound links fail closed, rather than adopting the current account.

Session cookie values must be exactly 43 characters of canonical unpadded base64url encoding of 32 bytes. Session.AuthTime is the method's actual verification time. Session.At is immutable verified-session creation time, never last-seen time or request time: legacy magic-link sessions can use it when AuthTime is absent. Keymail sessions cannot use that fallback.

On every authenticated app request, resolve Home sessions through Bridge.ResolveSession. Use the returned local ID for ownership and grants. Never pass an opaque Home subject through a helper that treats subjects as email addresses or creates a local account. Keep ordinary local sign-in's existing behavior in the app's local authentication path.

Routes supplies shared navigation, local reauthentication markers and the narrow callback exception to your app's CSRF middleware. Mount its methods alongside Bridge.Start, Callback, Finish and ConfirmPage. The local plugin's successful return must be LocalCompletePath. Its pending cookie must be __Host-rastrillo_pending, and the local entry is /signin/local. Mount exactly Bridge.Callback at POST /auth/assertion: this path alone bypasses CSRF protection because the bridge verifies its browser-bound assertion. LocalLandingPath optionally sets a validated local destination after ordinary local sign-in (default /); explicit account-link navigation takes precedence. Render shared pages inside the app's existing Estilo layout; all paths work without JavaScript. Apps with additional content-security directives must supply their existing policy with the validated Home issuer added to form-action.

Routes.Signin sends a person who already has a live session straight to the validated return_to (or /) instead of starting another exchange. Routes.Signout ends the app session and then answers 307 to {Issuer}/signout, which ends the Home sign-in session too and returns the browser to the app's /signed-out. Home admits that hop only from an origin registered in its HOME_CONSUMERS, by Referer when the browser nulls Origin, so a page showing Sign out must not send Referrer-Policy: no-referrer (use strict-origin), and a custom policy must keep the issuer in form-action.

Wrap the trusted local plugin's Begin handler with OAuthContinuation when it can redirect to Keymail. Render the supplied destination with OAuthPage and the shared home-oauth-head and home-oauth templates inside your existing layout. The helper validates the client origin, /auth/callback, scope and PKCE method, then ends the POST with a no-store continuation page so Safari does not apply form-action to Keymail's redirect chain. It does not discover or trust arbitrary request-provided destinations. Keep the existing local plugin callback route.

Extraction record

The link proof protocol, bridge, freshness rules and navigation originate in Oficina Docs commit 3fffd1be535ec87ab6e92da753046a4f1e4c754c, whose tree matches reviewed deployment a8f5c0e1d67ad042e89793aa941135eacd98aa23. The original files live under internal/docs/home_* and internal/docs/linkstore. This extraction preserves the consumed proof stages, nonce/session binding, clock watermark, freshness windows and encrypted flow purpose strings.

Changes are the neutral session DTO and app lookup hooks, new home_* link tables, app-selected encryption namespace, and shared rendering/navigation. The local-person foreign key becomes a transaction-scoped existence/admission lookup, because apps use different local identity tables. Every link write and subsequent resolution still checks the current local account. Additive migration 0002 adds a keyed person binding; earlier unbound rows fail closed. OAuth continuation also derives from Docs internal/docs/auth_navigation.go.

The original Docs state-machine tests were ported with synthetic session and local-account hooks. The app-owned content-preservation test now checks an unchanged content row; framework CSRF coverage belongs to the shared Routes and each app's router integration tests. Existing Docs tables and bytes are untouched. This is not a migration path for an already deployed Docs instance.