@schemavaults/auth-common 0.25.1 → 0.26.1

package/dist/oidc/endpoints.d.ts

@@ -0,0 +1,32 @@
+/**
+ * OIDC / OAuth2 endpoint paths served by the auth server, relative to
+ * its issuer identifier (the auth server URL).
+ *
+ * Single source of truth shared by:
+ *   - the auth server's discovery document
+ *     (`/.well-known/openid-configuration`), which advertises these
+ *     absolute URLs, and
+ *   - `@schemavaults/auth-client-sdk`, which builds its `openid-client`
+ *     Configuration statically from the same paths (skipping a discovery
+ *     round trip on every client instantiation).
+ *
+ * The SDK and server must agree byte-for-byte on these, so they are
+ * never hardcoded at either end.
+ */
+export declare const OIDC_ENDPOINT_PATHS: {
+    readonly discovery: "/.well-known/openid-configuration";
+    readonly authorization: "/api/oidc/authorize";
+    readonly token: "/api/oidc/token";
+    readonly userinfo: "/api/oidc/userinfo";
+    readonly introspection: "/api/oidc/introspect";
+    readonly jwks: "/api/oidc/jwks";
+};
+export type OidcEndpointName = keyof typeof OIDC_ENDPOINT_PATHS;
+/**
+ * Resolves an OIDC endpoint to its absolute URL for the given issuer.
+ *
+ * `issuer` is the auth server URL exactly as it appears in the `iss`
+ * claim (never with a trailing slash — see `getAuthServerUrl()`); a
+ * trailing slash is tolerated and stripped so the result is stable.
+ */
+export declare function getOidcEndpointUrl(issuer: string, endpoint: OidcEndpointName): string;

package/dist/oidc/endpoints.js

@@ -0,0 +1,42 @@
+/**
+ * OIDC / OAuth2 endpoint paths served by the auth server, relative to
+ * its issuer identifier (the auth server URL).
+ *
+ * Single source of truth shared by:
+ *   - the auth server's discovery document
+ *     (`/.well-known/openid-configuration`), which advertises these
+ *     absolute URLs, and
+ *   - `@schemavaults/auth-client-sdk`, which builds its `openid-client`
+ *     Configuration statically from the same paths (skipping a discovery
+ *     round trip on every client instantiation).
+ *
+ * The SDK and server must agree byte-for-byte on these, so they are
+ * never hardcoded at either end.
+ */
+export const OIDC_ENDPOINT_PATHS = {
+    discovery: "/.well-known/openid-configuration",
+    authorization: "/api/oidc/authorize",
+    token: "/api/oidc/token",
+    userinfo: "/api/oidc/userinfo",
+    introspection: "/api/oidc/introspect",
+    jwks: "/api/oidc/jwks",
+};
+/**
+ * Resolves an OIDC endpoint to its absolute URL for the given issuer.
+ *
+ * `issuer` is the auth server URL exactly as it appears in the `iss`
+ * claim (never with a trailing slash — see `getAuthServerUrl()`); a
+ * trailing slash is tolerated and stripped so the result is stable.
+ */
+export function getOidcEndpointUrl(issuer, endpoint) {
+    if (typeof issuer !== "string" || issuer.length === 0) {
+        throw new TypeError("Expected 'issuer' to be a non-empty string!");
+    }
+    const path = OIDC_ENDPOINT_PATHS[endpoint];
+    if (typeof path !== "string") {
+        throw new RangeError(`Unknown OIDC endpoint '${String(endpoint)}'`);
+    }
+    const base = issuer.endsWith("/") ? issuer.slice(0, -1) : issuer;
+    return `${base}${path}`;
+}
+//# sourceMappingURL=endpoints.js.map

package/dist/oidc/endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../../src/oidc/endpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,SAAS,EAAE,mCAAmC;IAC9C,aAAa,EAAE,qBAAqB;IACpC,KAAK,EAAE,iBAAiB;IACxB,QAAQ,EAAE,oBAAoB;IAC9B,aAAa,EAAE,sBAAsB;IACrC,IAAI,EAAE,gBAAgB;CACyB,CAAC;AAIlD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,QAA0B;IAE1B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,SAAS,CAAC,6CAA6C,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,IAAI,GAA6B,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACrE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,UAAU,CAAC,0BAA0B,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,IAAI,GAAW,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACzE,OAAO,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC;AAC1B,CAAC"}

package/dist/oidc/index.d.ts

@@ -5,3 +5,9 @@ export type { OidcNonce } from "./nonce";
 export { OIDC_SUB_CLAIM_DELIMITER, formatOidcSubClaim, parseOidcSubClaim, } from "./sub-claim";
 export { buildOidcProfileClaims } from "./profile-claims";
 export type { OidcProfileClaims, OidcProfileClaimsSource, } from "./profile-claims";
+export { OIDC_ENDPOINT_PATHS, getOidcEndpointUrl } from "./endpoints";
+export type { OidcEndpointName } from "./endpoints";
+export { OIDC_TOKEN_RESOURCE_PARAM, OIDC_TOKEN_REFRESH_TOKEN_DELIVERY_PARAM, OIDC_REFRESH_TOKEN_DELIVERY_MODES, oidcRefreshTokenDeliveryModeSchema, DEFAULT_OIDC_REFRESH_TOKEN_DELIVERY_MODE, OIDC_TOKEN_REFRESH_TOKEN_EXPIRES_IN_FIELD, oidcTokenResponseExtensionsSchema, } from "./token-endpoint-extensions";
+export type { OidcRefreshTokenDeliveryMode, OidcTokenResponseExtensions, } from "./token-endpoint-extensions";
+export { buildOidcProviderMetadata } from "./provider-metadata";
+export type { OidcProviderMetadata } from "./provider-metadata";

package/dist/oidc/index.js

@@ -2,4 +2,7 @@ export { OIDC_OPENID_SCOPE, OIDC_SUPPORTED_SCOPES, DEFAULT_AUTH_SCOPE, OIDC_SCOP
 export { oidcNonceSchema, OIDC_NONCE_VSCHAR_REGEX, parseOidcNonce, OidcNonceValidationError, } from "./nonce";
 export { OIDC_SUB_CLAIM_DELIMITER, formatOidcSubClaim, parseOidcSubClaim, } from "./sub-claim";
 export { buildOidcProfileClaims } from "./profile-claims";
+export { OIDC_ENDPOINT_PATHS, getOidcEndpointUrl } from "./endpoints";
+export { OIDC_TOKEN_RESOURCE_PARAM, OIDC_TOKEN_REFRESH_TOKEN_DELIVERY_PARAM, OIDC_REFRESH_TOKEN_DELIVERY_MODES, oidcRefreshTokenDeliveryModeSchema, DEFAULT_OIDC_REFRESH_TOKEN_DELIVERY_MODE, OIDC_TOKEN_REFRESH_TOKEN_EXPIRES_IN_FIELD, oidcTokenResponseExtensionsSchema, } from "./token-endpoint-extensions";
+export { buildOidcProviderMetadata } from "./provider-metadata";
 //# sourceMappingURL=index.js.map

package/dist/oidc/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/oidc/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAOjB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,cAAc,EACd,wBAAwB,GACzB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/oidc/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAOjB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,cAAc,EACd,wBAAwB,GACzB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAM1D,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtE,OAAO,EACL,yBAAyB,EACzB,uCAAuC,EACvC,iCAAiC,EACjC,kCAAkC,EAClC,wCAAwC,EACxC,yCAAyC,EACzC,iCAAiC,GAClC,MAAM,6BAA6B,CAAC;AAMrC,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/oidc/provider-metadata.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OpenID Provider Metadata (OIDC Discovery 1.0 §3 / RFC 8414) for the
+ * auth server, as a pure function of its issuer identifier.
+ *
+ * Single source of truth consumed by BOTH ends of the protocol:
+ *   - the auth server serves it verbatim at
+ *     /.well-known/openid-configuration, and
+ *   - `@schemavaults/auth-client-sdk` hands the same object to
+ *     `openid-client` as its server metadata instead of fetching the
+ *     document (so the SDK can never drift from what the server
+ *     advertises — a change here changes both sides together).
+ *
+ * `issuer` MUST be byte-identical to the `iss` claim in id_tokens and
+ * the `iss` authorization-response parameter — both derive from the auth
+ * server URL, which never carries a trailing slash.
+ */
+/**
+ * The advertised metadata. List fields are plain mutable arrays because
+ * that is how `openid-client` types its `ServerMetadata`; treat them as
+ * read-only in practice (every call builds a fresh document). Declared
+ * as a type alias (not an interface) so it carries the implicit index
+ * signature `openid-client`'s metadata type requires.
+ */
+export type OidcProviderMetadata = {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    introspection_endpoint: string;
+    jwks_uri: string;
+    response_types_supported: string[];
+    response_modes_supported: string[];
+    grant_types_supported: string[];
+    subject_types_supported: string[];
+    id_token_signing_alg_values_supported: string[];
+    scopes_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    introspection_endpoint_auth_methods_supported: string[];
+    code_challenge_methods_supported: string[];
+    claims_supported: string[];
+    authorization_response_iss_parameter_supported: boolean;
+    request_parameter_supported: boolean;
+    request_uri_parameter_supported: boolean;
+};
+/**
+ * Builds the provider metadata for the auth server at `issuer`. A
+ * trailing slash on `issuer` is stripped so the endpoints and the
+ * `issuer` field stay consistent with the `iss` claim.
+ */
+export declare function buildOidcProviderMetadata(issuer: string): OidcProviderMetadata;
+export default buildOidcProviderMetadata;

package/dist/oidc/provider-metadata.js

@@ -0,0 +1,94 @@
+/**
+ * OpenID Provider Metadata (OIDC Discovery 1.0 §3 / RFC 8414) for the
+ * auth server, as a pure function of its issuer identifier.
+ *
+ * Single source of truth consumed by BOTH ends of the protocol:
+ *   - the auth server serves it verbatim at
+ *     /.well-known/openid-configuration, and
+ *   - `@schemavaults/auth-client-sdk` hands the same object to
+ *     `openid-client` as its server metadata instead of fetching the
+ *     document (so the SDK can never drift from what the server
+ *     advertises — a change here changes both sides together).
+ *
+ * `issuer` MUST be byte-identical to the `iss` claim in id_tokens and
+ * the `iss` authorization-response parameter — both derive from the auth
+ * server URL, which never carries a trailing slash.
+ */
+import { getOidcEndpointUrl } from "./endpoints";
+import { OIDC_SUPPORTED_SCOPES } from "./scope";
+/**
+ * Builds the provider metadata for the auth server at `issuer`. A
+ * trailing slash on `issuer` is stripped so the endpoints and the
+ * `issuer` field stay consistent with the `iss` claim.
+ */
+export function buildOidcProviderMetadata(issuer) {
+    if (typeof issuer !== "string" || issuer.length === 0) {
+        throw new TypeError("Expected 'issuer' to be a non-empty string!");
+    }
+    const normalized_issuer = issuer.endsWith("/")
+        ? issuer.slice(0, -1)
+        : issuer;
+    return {
+        issuer: normalized_issuer,
+        authorization_endpoint: getOidcEndpointUrl(normalized_issuer, "authorization"),
+        token_endpoint: getOidcEndpointUrl(normalized_issuer, "token"),
+        userinfo_endpoint: getOidcEndpointUrl(normalized_issuer, "userinfo"),
+        introspection_endpoint: getOidcEndpointUrl(normalized_issuer, "introspection"),
+        jwks_uri: getOidcEndpointUrl(normalized_issuer, "jwks"),
+        response_types_supported: ["code"],
+        response_modes_supported: ["query"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        subject_types_supported: ["public"],
+        id_token_signing_alg_values_supported: ["RS256"],
+        scopes_supported: [...OIDC_SUPPORTED_SCOPES],
+        // Apps without a registered client secret are public clients
+        // ("none"); apps with one are confidential clients and must
+        // authenticate via client_secret_basic or client_secret_post.
+        // PKCE S256 is mandatory for every client either way.
+        token_endpoint_auth_methods_supported: [
+            "none",
+            "client_secret_basic",
+            "client_secret_post",
+        ],
+        // RFC 7662 token introspection (advertised per RFC 8414 §2). "none"
+        // is deliberately absent: §2.1 requires the endpoint to be
+        // authorized, so only confidential clients may introspect.
+        introspection_endpoint_auth_methods_supported: [
+            "client_secret_basic",
+            "client_secret_post",
+        ],
+        code_challenge_methods_supported: ["S256"],
+        claims_supported: [
+            "sub",
+            "iss",
+            "aud",
+            "exp",
+            "iat",
+            "nonce",
+            "email",
+            "email_verified",
+            // Profile-scoped claims (OIDC Core §5.1), derived from the user's
+            // stored profile name fields; emitted only when set.
+            "name",
+            "given_name",
+            "middle_name",
+            "family_name",
+            "preferred_username",
+        ],
+        // RFC 9207: the auth server puts `iss` on every authorization
+        // response. Advertising it makes spec-compliant clients (including
+        // the platform SDK via openid-client) require and verify it on
+        // redirect callbacks — authorization-server mix-up protection.
+        authorization_response_iss_parameter_supported: true,
+        // Request Objects (JAR, OIDC Core §6 / RFC 9101) are not implemented;
+        // the authorize endpoint rejects `request`/`request_uri` with
+        // request_not_supported / request_uri_not_supported. Declared
+        // explicitly because OIDC Discovery §3 defaults
+        // request_uri_parameter_supported to TRUE when omitted — leaving it
+        // out would falsely advertise support.
+        request_parameter_supported: false,
+        request_uri_parameter_supported: false,
+    };
+}
+export default buildOidcProviderMetadata;
+//# sourceMappingURL=provider-metadata.js.map

package/dist/oidc/provider-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-metadata.js","sourceRoot":"","sources":["../../src/oidc/provider-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AA+BhD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAc;IAEd,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,SAAS,CAAC,6CAA6C,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,iBAAiB,GAAW,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QACpD,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrB,CAAC,CAAC,MAAM,CAAC;IAEX,OAAO;QACL,MAAM,EAAE,iBAAiB;QACzB,sBAAsB,EAAE,kBAAkB,CAAC,iBAAiB,EAAE,eAAe,CAAC;QAC9E,cAAc,EAAE,kBAAkB,CAAC,iBAAiB,EAAE,OAAO,CAAC;QAC9D,iBAAiB,EAAE,kBAAkB,CAAC,iBAAiB,EAAE,UAAU,CAAC;QACpE,sBAAsB,EAAE,kBAAkB,CACxC,iBAAiB,EACjB,eAAe,CAChB;QACD,QAAQ,EAAE,kBAAkB,CAAC,iBAAiB,EAAE,MAAM,CAAC;QACvD,wBAAwB,EAAE,CAAC,MAAM,CAAC;QAClC,wBAAwB,EAAE,CAAC,OAAO,CAAC;QACnC,qBAAqB,EAAE,CAAC,oBAAoB,EAAE,eAAe,CAAC;QAC9D,uBAAuB,EAAE,CAAC,QAAQ,CAAC;QACnC,qCAAqC,EAAE,CAAC,OAAO,CAAC;QAChD,gBAAgB,EAAE,CAAC,GAAG,qBAAqB,CAAC;QAC5C,6DAA6D;QAC7D,4DAA4D;QAC5D,8DAA8D;QAC9D,sDAAsD;QACtD,qCAAqC,EAAE;YACrC,MAAM;YACN,qBAAqB;YACrB,oBAAoB;SACrB;QACD,oEAAoE;QACpE,2DAA2D;QAC3D,2DAA2D;QAC3D,6CAA6C,EAAE;YAC7C,qBAAqB;YACrB,oBAAoB;SACrB;QACD,gCAAgC,EAAE,CAAC,MAAM,CAAC;QAC1C,gBAAgB,EAAE;YAChB,KAAK;YACL,KAAK;YACL,KAAK;YACL,KAAK;YACL,KAAK;YACL,OAAO;YACP,OAAO;YACP,gBAAgB;YAChB,kEAAkE;YAClE,qDAAqD;YACrD,MAAM;YACN,YAAY;YACZ,aAAa;YACb,aAAa;YACb,oBAAoB;SACrB;QACD,8DAA8D;QAC9D,mEAAmE;QACnE,+DAA+D;QAC/D,+DAA+D;QAC/D,8CAA8C,EAAE,IAAI;QACpD,sEAAsE;QACtE,8DAA8D;QAC9D,8DAA8D;QAC9D,gDAAgD;QAChD,oEAAoE;QACpE,uCAAuC;QACvC,2BAA2B,EAAE,KAAK;QAClC,+BAA+B,EAAE,KAAK;KACvC,CAAC;AACJ,CAAC;AAED,eAAe,yBAAyB,CAAC"}

package/dist/oidc/token-endpoint-extensions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Token-endpoint request/response parameters used by the SchemaVaults
+ * SDKs on top of the standard OIDC token endpoint (`/api/oidc/token`).
+ *
+ * The platform's SDK clients need two things a plain OIDC relying party
+ * does not:
+ *
+ *   1. Access tokens for arbitrary registered API servers (the platform's
+ *      authorization model is audience-based). This uses the STANDARD
+ *      RFC 8707 `resource` parameter: the token endpoint mints the
+ *      response's `access_token` for that audience instead of the
+ *      reserved `oidc-userinfo` audience. Exactly one `resource` per
+ *      token request (the platform issues one encrypted access token per
+ *      audience, so it "only supports issuing an access token with a
+ *      single audience" in RFC 8707 §2 terms).
+ *
+ *   2. Refresh tokens kept out of JavaScript for browser clients. This
+ *      is a platform extension: the `refresh_token_delivery` request
+ *      parameter asks the endpoint to set the refresh token as an
+ *      HTTP-only cookie (scoped to the client app, on the auth server's
+ *      domain) and OMIT `refresh_token` from the JSON body. RFC 6749
+ *      §5.1 makes `refresh_token` OPTIONAL in the response, so
+ *      spec-compliant client libraries (e.g. `openid-client`) accept
+ *      such responses unchanged. The response always carries the
+ *      extension field `refresh_token_expires_in` (seconds) so the client
+ *      can track the session lifetime either way.
+ *
+ * Relying parties that send neither parameter get the plain OIDC
+ * behavior (userinfo-audience access token, refresh token inlined).
+ */
+import { z } from "zod";
+/** RFC 8707 Resource Indicators request parameter name. */
+export declare const OIDC_TOKEN_RESOURCE_PARAM: "resource";
+/** Platform extension: how the refresh token is delivered to the client. */
+export declare const OIDC_TOKEN_REFRESH_TOKEN_DELIVERY_PARAM: "refresh_token_delivery";
+export declare const OIDC_REFRESH_TOKEN_DELIVERY_MODES: readonly ["inline", "http_only_cookie"];
+export declare const oidcRefreshTokenDeliveryModeSchema: z.ZodEnum<{
+    inline: "inline";
+    http_only_cookie: "http_only_cookie";
+}>;
+export type OidcRefreshTokenDeliveryMode = z.infer<typeof oidcRefreshTokenDeliveryModeSchema>;
+export declare const DEFAULT_OIDC_REFRESH_TOKEN_DELIVERY_MODE: "inline";
+/**
+ * Platform extension response field: seconds until the (possibly
+ * cookie-delivered) refresh token expires. Named after the widely used
+ * non-standard field of the same name (GitHub, Keycloak's
+ * `refresh_expires_in`, ...).
+ */
+export declare const OIDC_TOKEN_REFRESH_TOKEN_EXPIRES_IN_FIELD: "refresh_token_expires_in";
+/**
+ * Shape of the extension fields the SDK reads off a token response.
+ * `refresh_token_expires_in` is emitted by the auth server on every
+ * successful response whose grant issued a refresh token.
+ */
+export declare const oidcTokenResponseExtensionsSchema: z.ZodObject<{
+    refresh_token_expires_in: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type OidcTokenResponseExtensions = z.infer<typeof oidcTokenResponseExtensionsSchema>;

package/dist/oidc/token-endpoint-extensions.js

@@ -0,0 +1,69 @@
+/**
+ * Token-endpoint request/response parameters used by the SchemaVaults
+ * SDKs on top of the standard OIDC token endpoint (`/api/oidc/token`).
+ *
+ * The platform's SDK clients need two things a plain OIDC relying party
+ * does not:
+ *
+ *   1. Access tokens for arbitrary registered API servers (the platform's
+ *      authorization model is audience-based). This uses the STANDARD
+ *      RFC 8707 `resource` parameter: the token endpoint mints the
+ *      response's `access_token` for that audience instead of the
+ *      reserved `oidc-userinfo` audience. Exactly one `resource` per
+ *      token request (the platform issues one encrypted access token per
+ *      audience, so it "only supports issuing an access token with a
+ *      single audience" in RFC 8707 §2 terms).
+ *
+ *   2. Refresh tokens kept out of JavaScript for browser clients. This
+ *      is a platform extension: the `refresh_token_delivery` request
+ *      parameter asks the endpoint to set the refresh token as an
+ *      HTTP-only cookie (scoped to the client app, on the auth server's
+ *      domain) and OMIT `refresh_token` from the JSON body. RFC 6749
+ *      §5.1 makes `refresh_token` OPTIONAL in the response, so
+ *      spec-compliant client libraries (e.g. `openid-client`) accept
+ *      such responses unchanged. The response always carries the
+ *      extension field `refresh_token_expires_in` (seconds) so the client
+ *      can track the session lifetime either way.
+ *
+ * Relying parties that send neither parameter get the plain OIDC
+ * behavior (userinfo-audience access token, refresh token inlined).
+ */
+import { z } from "zod";
+/** RFC 8707 Resource Indicators request parameter name. */
+export const OIDC_TOKEN_RESOURCE_PARAM = "resource";
+/** Platform extension: how the refresh token is delivered to the client. */
+export const OIDC_TOKEN_REFRESH_TOKEN_DELIVERY_PARAM = "refresh_token_delivery";
+export const OIDC_REFRESH_TOKEN_DELIVERY_MODES = [
+    /** RFC 6749 §5.1 default: `refresh_token` inlined in the JSON body. */
+    "inline",
+    /**
+     * Refresh token set as an HTTP-only cookie (`refresh_token_<client_id>`
+     * plus the JS-readable `refresh_token_expiry_<client_id>` marker) and
+     * omitted from the JSON body.
+     */
+    "http_only_cookie",
+];
+export const oidcRefreshTokenDeliveryModeSchema = z.enum(OIDC_REFRESH_TOKEN_DELIVERY_MODES);
+export const DEFAULT_OIDC_REFRESH_TOKEN_DELIVERY_MODE = "inline";
+/**
+ * Platform extension response field: seconds until the (possibly
+ * cookie-delivered) refresh token expires. Named after the widely used
+ * non-standard field of the same name (GitHub, Keycloak's
+ * `refresh_expires_in`, ...).
+ */
+export const OIDC_TOKEN_REFRESH_TOKEN_EXPIRES_IN_FIELD = "refresh_token_expires_in";
+/**
+ * Shape of the extension fields the SDK reads off a token response.
+ * `refresh_token_expires_in` is emitted by the auth server on every
+ * successful response whose grant issued a refresh token.
+ */
+export const oidcTokenResponseExtensionsSchema = z
+    .object({
+    [OIDC_TOKEN_REFRESH_TOKEN_EXPIRES_IN_FIELD]: z
+        .number()
+        .int()
+        .positive()
+        .optional(),
+})
+    .loose();
+//# sourceMappingURL=token-endpoint-extensions.js.map

package/dist/oidc/token-endpoint-extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-endpoint-extensions.js","sourceRoot":"","sources":["../../src/oidc/token-endpoint-extensions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,2DAA2D;AAC3D,MAAM,CAAC,MAAM,yBAAyB,GAAG,UAAmB,CAAC;AAE7D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,uCAAuC,GAClD,wBAAiC,CAAC;AAEpC,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,uEAAuE;IACvE,QAAQ;IACR;;;;OAIG;IACH,kBAAkB;CACV,CAAC;AAEX,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAC,IAAI,CACtD,iCAAiC,CAClC,CAAC;AAMF,MAAM,CAAC,MAAM,wCAAwC,GACnD,QAAwD,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yCAAyC,GACpD,0BAAmC,CAAC;AAEtC;;;;GAIG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC;KAC/C,MAAM,CAAC;IACN,CAAC,yCAAyC,CAAC,EAAE,CAAC;SAC3C,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,QAAQ,EAAE;CACd,CAAC;KACD,KAAK,EAAE,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schemavaults/auth-common",
   "description": "Types and utility functions for authentication and authorization",
-  "version": "0.25.1",
+  "version": "0.26.1",
   "license": "UNLICENSED",
   "private": false,
   "repository": {