@broberg/sso 0.8.0 → 0.10.0

package/dist/hono.d.cts

@@ -139,6 +139,15 @@ interface Discovery {
     userinfo_endpoint?: string;
     end_session_endpoint?: string;
 }
+/** The signed-in user's own profile, as BID's GET /api/app/profile returns it. */
+interface BidProfile {
+    sub: string;
+    name: string | null;
+    picture: string | null;
+    email: string | null;
+    /** BID's own account page — mail, password, passkeys, 2FA and sessions live there. */
+    account_url: string;
+}
 /**
  * What `beginLogin` produces. Every field except `url` must survive the round
  * trip to BID and back — the adapter stores them in a short-lived cookie.
@@ -177,6 +186,8 @@ interface LoginResult {
     idToken: string;
     accessToken?: string;
     refreshToken?: string;
+    /** Seconds the access token lives, when BID said so (`expires_in`). */
+    expiresIn?: number;
 }
 /**
  * `prompt=none` asks BID to answer WITHOUT showing anything (components-F084.6).
@@ -216,6 +227,16 @@ interface SsoClient {
      * answers — see the implementation for why that must never become "unverified".
      */
     addressOwnership(accessToken: string, address: string): Promise<AddressOwnership>;
+    /**
+     * F095.1 — trade a refresh token for a new access token (`grant_type=refresh_token`).
+     * Throws SsoError on refusal; the message carries the status and BID's error
+     * code, never a token.
+     */
+    refreshTokens(refreshToken: string): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+    }>;
     /**
      * Invite users to BID on behalf of this app (the app's OWN key, `bidk_…`).
      * One result per email. Throws SsoError on anything BID did not clearly say.
@@ -232,6 +253,21 @@ interface SsoClient {
      * Throws SsoError on anything that is not a valid, sub-only logout token.
      */
     verifyLogoutToken(token: string): Promise<LogoutToken>;
+    /**
+     * F095.2 — the signed-in user's own profile (scope `profile`), with the user's
+     * access token. Throws SsoAppApiError on any refusal.
+     */
+    getProfile(accessToken: string): Promise<BidProfile>;
+    /** F095.2 — change the user's own name (scope `profile:write`). Returns the new profile. */
+    updateProfile(accessToken: string, name: string): Promise<BidProfile>;
+    /**
+     * F095.2 — replace the user's picture (scope `profile:write`). Refuses more than
+     * MAX_AVATAR_BYTES or a type outside AVATAR_TYPES with SsoAvatarRejectedError
+     * BEFORE anything is sent.
+     */
+    uploadAvatar(accessToken: string, bytes: Uint8Array | ArrayBuffer, contentType: string): Promise<BidProfile>;
+    /** F095.2 — remove the user's picture (scope `profile:write`). */
+    removeAvatar(accessToken: string): Promise<BidProfile>;
     /** Exposed for tests and for a health check; not needed in normal use. */
     readonly jwks: JwksCache;
 }
@@ -271,6 +307,41 @@ interface LogoutToken {
     exp: number;
 }
 
+/**
+ * Server-side tokens for calling Broberg ID on the user's behalf (F095.1).
+ *
+ * The login already RECEIVES an access token and a refresh token; before 0.9.0
+ * ssoRoutes dropped both, so an app could not call BID's app API (the account
+ * page: read and change your own name and picture) as the user.
+ *
+ * ── WHY NOT IN THE COOKIE ────────────────────────────────────────────────
+ * The session cookie is SIGNED, not encrypted, and the browser can read it. A
+ * refresh token is the longest-lived, highest-value credential in the whole
+ * flow: whoever holds it can mint access tokens until it is revoked. So the
+ * tokens live server-side, keyed by a random `sid` that is the only thing the
+ * cookie carries. A stolen cookie still needs the server to be useful.
+ */
+interface TokenSet {
+    /** The BID subject the tokens belong to — lets «Log ud overalt» find them. */
+    sub: string;
+    accessToken: string;
+    refreshToken?: string;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+/**
+ * Where the tokens live. The APP provides it in production, backed by
+ * something every instance shares (SQLite on one machine, a database or Redis
+ * on several) — the same reason BackchannelStore has no in-memory default.
+ */
+interface TokenStore {
+    get(sid: string): Promise<TokenSet | undefined>;
+    set(sid: string, tokens: TokenSet): Promise<void>;
+    delete(sid: string): Promise<void>;
+    /** Drop every token set for `sub` — what «Log ud overalt» calls. */
+    deleteSub(sub: string): Promise<void>;
+}
+
 /**
  * The app's OWN session cookie — signed, not encrypted.
  *
@@ -296,6 +367,12 @@ interface SessionPayload {
      * older than any logout.
      */
     iat?: number;
+    /**
+     * F095.1 — the key to this session's server-side tokens (ssoRoutes'
+     * `tokenStore`). Random, 128 bits. The tokens themselves are NEVER in the
+     * cookie: it is signed, not encrypted, and the browser can read it.
+     */
+    sid?: string;
     /** Optional convenience copies; never authorisation data. */
     email?: string;
     name?: string;
@@ -356,6 +433,12 @@ interface SsoRoutesOptions {
     loginPath?: string;
     /** Where to send a user after a successful login when no returnTo is given. */
     defaultReturnTo?: string;
+    /**
+     * F095.1 — keep the user's access and refresh token SERVER-SIDE, so the app
+     * can call BID's app API (the account page) as the user via getAccessToken.
+     * Without it, login behaves exactly as in 0.8.0 and the tokens are dropped.
+     */
+    tokenStore?: TokenStore;
 }
 declare function ssoRoutes(options?: SsoRoutesOptions): {
     app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
@@ -363,10 +446,34 @@ declare function ssoRoutes(options?: SsoRoutesOptions): {
     require: MiddlewareHandler;
     client: SsoClient;
     config: SsoConfig;
+    getAccessToken: (c: Context) => Promise<string>;
 };
 /** Why a login transaction could not be read back. Three states, three answers. */
 type TransactionFailure = "absent" | "expired" | "unreadable";
 /** Read the session a middleware attached. */
 declare function getSession(c: Context): SessionPayload | null;
+/** What accountRoutes needs from ssoRoutes — pass its return value as is. */
+interface AccountRoutesInput {
+    client: Pick<SsoClient, "getProfile" | "updateProfile" | "uploadAvatar" | "removeAvatar">;
+    getAccessToken(c: Context): Promise<string>;
+}
+/**
+ * The signed-in user's own name and picture, for the app's account page.
+ * Mount it on /api/account:
+ *
+ *   const sso = ssoRoutes({ tokenStore });
+ *   app.route("/api/account", accountRoutes(sso));
+ *
+ * GET /profile · POST /profile {name} · POST /profile/avatar (raw image body) ·
+ * POST /profile/avatar/remove. Every answer is JSON, refusals included — it is
+ * an API, so never a login redirect:
+ *   401 {error:"unauthenticated"}            no live session
+ *   401 {error:"reauth"}                     the session's tokens are spent — log in again
+ *   403 {error:"insufficient_scope", scope}  log in again with that scope requested
+ *   413 / 415                                picture too large / not PNG, JPEG or WebP
+ *   4xx {error:<BID's code>}                 BID refused the change (e.g. an invalid name)
+ *   502 {error:"bid_unavailable"}            BID did not answer usably
+ */
+declare function accountRoutes(sso: AccountRoutesInput): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 
-export { type BackchannelOptions, type BackchannelStore, type SsoRoutesOptions, type TransactionFailure, getSession, ssoRoutes };
+export { type AccountRoutesInput, type BackchannelOptions, type BackchannelStore, type SsoRoutesOptions, type TransactionFailure, accountRoutes, getSession, ssoRoutes };

package/dist/hono.d.ts

@@ -139,6 +139,15 @@ interface Discovery {
     userinfo_endpoint?: string;
     end_session_endpoint?: string;
 }
+/** The signed-in user's own profile, as BID's GET /api/app/profile returns it. */
+interface BidProfile {
+    sub: string;
+    name: string | null;
+    picture: string | null;
+    email: string | null;
+    /** BID's own account page — mail, password, passkeys, 2FA and sessions live there. */
+    account_url: string;
+}
 /**
  * What `beginLogin` produces. Every field except `url` must survive the round
  * trip to BID and back — the adapter stores them in a short-lived cookie.
@@ -177,6 +186,8 @@ interface LoginResult {
     idToken: string;
     accessToken?: string;
     refreshToken?: string;
+    /** Seconds the access token lives, when BID said so (`expires_in`). */
+    expiresIn?: number;
 }
 /**
  * `prompt=none` asks BID to answer WITHOUT showing anything (components-F084.6).
@@ -216,6 +227,16 @@ interface SsoClient {
      * answers — see the implementation for why that must never become "unverified".
      */
     addressOwnership(accessToken: string, address: string): Promise<AddressOwnership>;
+    /**
+     * F095.1 — trade a refresh token for a new access token (`grant_type=refresh_token`).
+     * Throws SsoError on refusal; the message carries the status and BID's error
+     * code, never a token.
+     */
+    refreshTokens(refreshToken: string): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+    }>;
     /**
      * Invite users to BID on behalf of this app (the app's OWN key, `bidk_…`).
      * One result per email. Throws SsoError on anything BID did not clearly say.
@@ -232,6 +253,21 @@ interface SsoClient {
      * Throws SsoError on anything that is not a valid, sub-only logout token.
      */
     verifyLogoutToken(token: string): Promise<LogoutToken>;
+    /**
+     * F095.2 — the signed-in user's own profile (scope `profile`), with the user's
+     * access token. Throws SsoAppApiError on any refusal.
+     */
+    getProfile(accessToken: string): Promise<BidProfile>;
+    /** F095.2 — change the user's own name (scope `profile:write`). Returns the new profile. */
+    updateProfile(accessToken: string, name: string): Promise<BidProfile>;
+    /**
+     * F095.2 — replace the user's picture (scope `profile:write`). Refuses more than
+     * MAX_AVATAR_BYTES or a type outside AVATAR_TYPES with SsoAvatarRejectedError
+     * BEFORE anything is sent.
+     */
+    uploadAvatar(accessToken: string, bytes: Uint8Array | ArrayBuffer, contentType: string): Promise<BidProfile>;
+    /** F095.2 — remove the user's picture (scope `profile:write`). */
+    removeAvatar(accessToken: string): Promise<BidProfile>;
     /** Exposed for tests and for a health check; not needed in normal use. */
     readonly jwks: JwksCache;
 }
@@ -271,6 +307,41 @@ interface LogoutToken {
     exp: number;
 }
 
+/**
+ * Server-side tokens for calling Broberg ID on the user's behalf (F095.1).
+ *
+ * The login already RECEIVES an access token and a refresh token; before 0.9.0
+ * ssoRoutes dropped both, so an app could not call BID's app API (the account
+ * page: read and change your own name and picture) as the user.
+ *
+ * ── WHY NOT IN THE COOKIE ────────────────────────────────────────────────
+ * The session cookie is SIGNED, not encrypted, and the browser can read it. A
+ * refresh token is the longest-lived, highest-value credential in the whole
+ * flow: whoever holds it can mint access tokens until it is revoked. So the
+ * tokens live server-side, keyed by a random `sid` that is the only thing the
+ * cookie carries. A stolen cookie still needs the server to be useful.
+ */
+interface TokenSet {
+    /** The BID subject the tokens belong to — lets «Log ud overalt» find them. */
+    sub: string;
+    accessToken: string;
+    refreshToken?: string;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+/**
+ * Where the tokens live. The APP provides it in production, backed by
+ * something every instance shares (SQLite on one machine, a database or Redis
+ * on several) — the same reason BackchannelStore has no in-memory default.
+ */
+interface TokenStore {
+    get(sid: string): Promise<TokenSet | undefined>;
+    set(sid: string, tokens: TokenSet): Promise<void>;
+    delete(sid: string): Promise<void>;
+    /** Drop every token set for `sub` — what «Log ud overalt» calls. */
+    deleteSub(sub: string): Promise<void>;
+}
+
 /**
  * The app's OWN session cookie — signed, not encrypted.
  *
@@ -296,6 +367,12 @@ interface SessionPayload {
      * older than any logout.
      */
     iat?: number;
+    /**
+     * F095.1 — the key to this session's server-side tokens (ssoRoutes'
+     * `tokenStore`). Random, 128 bits. The tokens themselves are NEVER in the
+     * cookie: it is signed, not encrypted, and the browser can read it.
+     */
+    sid?: string;
     /** Optional convenience copies; never authorisation data. */
     email?: string;
     name?: string;
@@ -356,6 +433,12 @@ interface SsoRoutesOptions {
     loginPath?: string;
     /** Where to send a user after a successful login when no returnTo is given. */
     defaultReturnTo?: string;
+    /**
+     * F095.1 — keep the user's access and refresh token SERVER-SIDE, so the app
+     * can call BID's app API (the account page) as the user via getAccessToken.
+     * Without it, login behaves exactly as in 0.8.0 and the tokens are dropped.
+     */
+    tokenStore?: TokenStore;
 }
 declare function ssoRoutes(options?: SsoRoutesOptions): {
     app: Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
@@ -363,10 +446,34 @@ declare function ssoRoutes(options?: SsoRoutesOptions): {
     require: MiddlewareHandler;
     client: SsoClient;
     config: SsoConfig;
+    getAccessToken: (c: Context) => Promise<string>;
 };
 /** Why a login transaction could not be read back. Three states, three answers. */
 type TransactionFailure = "absent" | "expired" | "unreadable";
 /** Read the session a middleware attached. */
 declare function getSession(c: Context): SessionPayload | null;
+/** What accountRoutes needs from ssoRoutes — pass its return value as is. */
+interface AccountRoutesInput {
+    client: Pick<SsoClient, "getProfile" | "updateProfile" | "uploadAvatar" | "removeAvatar">;
+    getAccessToken(c: Context): Promise<string>;
+}
+/**
+ * The signed-in user's own name and picture, for the app's account page.
+ * Mount it on /api/account:
+ *
+ *   const sso = ssoRoutes({ tokenStore });
+ *   app.route("/api/account", accountRoutes(sso));
+ *
+ * GET /profile · POST /profile {name} · POST /profile/avatar (raw image body) ·
+ * POST /profile/avatar/remove. Every answer is JSON, refusals included — it is
+ * an API, so never a login redirect:
+ *   401 {error:"unauthenticated"}            no live session
+ *   401 {error:"reauth"}                     the session's tokens are spent — log in again
+ *   403 {error:"insufficient_scope", scope}  log in again with that scope requested
+ *   413 / 415                                picture too large / not PNG, JPEG or WebP
+ *   4xx {error:<BID's code>}                 BID refused the change (e.g. an invalid name)
+ *   502 {error:"bid_unavailable"}            BID did not answer usably
+ */
+declare function accountRoutes(sso: AccountRoutesInput): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
 
-export { type BackchannelOptions, type BackchannelStore, type SsoRoutesOptions, type TransactionFailure, getSession, ssoRoutes };
+export { type AccountRoutesInput, type BackchannelOptions, type BackchannelStore, type SsoRoutesOptions, type TransactionFailure, accountRoutes, getSession, ssoRoutes };