@spine-event-engine/auth 2.0.0-snapshot.2

package/dist/oidc/contracts.d.ts

@@ -0,0 +1,334 @@
+import type { AuthenticatedPrincipal, RequestCredential, ResolvedSession } from "../index.js";
+/**
+ * Clock used to evaluate finite OIDC transactions.
+ */
+export interface OidcFlowClock {
+    /**
+     * Returns a safe Unix epoch millisecond value in the Protobuf Timestamp range.
+     * @returns The current milliseconds.
+     */
+    now(): number;
+}
+/**
+ * Creates random OIDC state, nonce, and PKCE verifier material.
+ * @param length The required byte length.
+ * @returns The generated bytes.
+ */
+export type OidcFlowRandom = (length: number) => Uint8Array;
+/**
+ * A provider identity verified against its authorization-code response.
+ */
+export interface ExternalIdentity {
+    /**
+     * Identifies the verified provider issuer.
+     */
+    readonly issuer: string;
+    /**
+     * Identifies the provider subject.
+     */
+    readonly subject: string;
+    /**
+     * Provides verified provider claims.
+     */
+    readonly claims?: Readonly<Record<string, string>>;
+}
+/**
+ * Application identity produced by a provider-neutral mapping.
+ */
+export interface ResolvedApplicationIdentity {
+    /**
+     * Provides the verified provider identity.
+     */
+    readonly externalIdentity: ExternalIdentity;
+    /**
+     * Provides the mapped application principal.
+     */
+    readonly principal: AuthenticatedPrincipal;
+}
+/**
+ * Application-owned mapping from a verified external identity to a principal.
+ */
+export interface IdentityMapping {
+    /**
+     * Resolves a verified identity to an application principal.
+     * @param identity The verified provider identity.
+     * @param signal The operation cancellation signal.
+     * @returns The mapped identity, or undefined when it is not admitted.
+     */
+    resolve(identity: ExternalIdentity, signal: AbortSignal): Promise<ResolvedApplicationIdentity | undefined>;
+}
+/**
+ * Input to an adapter that exchanges and verifies an authorization code.
+ */
+export interface OidcAuthorizationCodeExchange {
+    /**
+     * Provides the provider authorization code.
+     */
+    readonly code: string;
+    /**
+     * Provides the configured OAuth client ID.
+     */
+    readonly clientId: string;
+    /**
+     * Provides the configured callback URI.
+     */
+    readonly callbackUri: string;
+    /**
+     * Provides the provider PKCE verifier.
+     */
+    readonly providerCodeVerifier: string;
+    /**
+     * Provides the nonce expected in the ID token.
+     */
+    readonly expectedNonce: string;
+    /**
+     * Cancels the provider exchange.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * Provider-specific authorization-code and identity-verification seam.
+ */
+export interface OidcVerifiedIdentityProvider {
+    /**
+     * Identifies the provider issuer.
+     */
+    readonly issuer: string;
+    /**
+     * Processes and verifies a provider authorization code.
+     * @param input The provider exchange input.
+     * @returns The verified identity, or undefined when verification fails.
+     */
+    exchangeAuthorizationCode(input: OidcAuthorizationCodeExchange): Promise<ExternalIdentity | undefined>;
+}
+/**
+ * Result issued by the application-selected application-session strategy.
+ */
+export interface ApplicationSessionIssue {
+    /**
+     * Provides the issued application credential.
+     */
+    readonly credential: RequestCredential;
+    /**
+     * Provides the issued application session.
+     */
+    readonly session: ResolvedSession;
+}
+/**
+ * Application-session seam used only after a successful OIDC grant exchange.
+ */
+export interface ApplicationSessionIssuer {
+    /**
+     * Creates an application session for a mapped principal.
+     * @param principal The mapped principal.
+     * @param signal The operation cancellation signal.
+     * @returns The issued session, or undefined when issuance fails.
+     */
+    issue(principal: AuthenticatedPrincipal, signal: AbortSignal): Promise<ApplicationSessionIssue | undefined>;
+}
+/**
+ * Construction options for the bounded, framework-neutral OIDC code flow.
+ */
+export interface OidcFlowOptions {
+    /**
+     * Provides the trusted authorization endpoint.
+     */
+    readonly authorizationEndpoint: string;
+    /**
+     * Provides the application callback URI.
+     */
+    readonly callbackUri: string;
+    /**
+     * Provides the OAuth client ID.
+     */
+    readonly clientId: string;
+    /**
+     * Provides requested provider scopes.
+     */
+    readonly scopes: readonly string[];
+    /**
+     * Provides permitted post-login redirects.
+     */
+    readonly allowedPostLoginRedirects: readonly string[];
+    /**
+     * Provides the verified identity provider.
+     */
+    readonly provider: OidcVerifiedIdentityProvider;
+    /**
+     * Maps verified identities to principals.
+     */
+    readonly identityMapping: IdentityMapping;
+    /**
+     * Issues application sessions.
+     */
+    readonly sessionIssuer: ApplicationSessionIssuer;
+    /**
+     * Provides the optional flow clock.
+     */
+    readonly clock?: OidcFlowClock;
+    /**
+     * Provides the optional random-byte source.
+     */
+    readonly randomBytes?: OidcFlowRandom;
+    /**
+     * Limits transaction lifetime in milliseconds.
+     */
+    readonly transactionTtlMilliseconds?: number;
+    /**
+     * Limits grant lifetime in milliseconds.
+     */
+    readonly grantTtlMilliseconds?: number;
+    /**
+     * Limits retained transactions.
+     */
+    readonly maxTransactions?: number;
+    /**
+     * Limits retained grants.
+     */
+    readonly maxGrants?: number;
+    /**
+     * Limits entropy collision retries.
+     */
+    readonly collisionAttempts?: number;
+    /**
+     * Limits provider-operation time in milliseconds.
+     */
+    readonly operationTimeoutMilliseconds?: number;
+    /**
+     * Limits authorization URL length.
+     */
+    readonly maxAuthorizationUrlLength?: number;
+}
+/**
+ * Input accepted by {@link OidcFlow.start}.
+ */
+export interface OidcFlowStartInput {
+    /**
+     * Browser-generated RFC 7636 S256 code challenge.
+     */
+    readonly browserCodeChallenge: string;
+    /**
+     * Exact preconfigured application redirect to use after successful sign-in.
+     */
+    readonly postLoginRedirect: string;
+}
+/**
+ * Result of opening one authorization-code transaction.
+ */
+export type OidcFlowStartResult = {
+    /**
+     * Identifies a started transaction.
+     */ readonly kind: "started";
+    /**
+     * Provides the authorization URL.
+     */ readonly authorizationUrl: string;
+    /**
+     * Provides transaction expiry milliseconds.
+     */ readonly expiresAt: number;
+} | {
+    /**
+     * Identifies a rejected transaction.
+     */
+    readonly kind: "rejected";
+    /**
+     * Explains why the transaction was rejected.
+     */
+    readonly reason: "invalid-input" | "capacity-exceeded" | "entropy-exhausted" | "clock-failure" | "closed";
+};
+/**
+ * Common callback facts. Exactly one of code or error is required.
+ */
+export interface OidcFlowCallbackBase {
+    /**
+     * Provides the one-time callback state.
+     */
+    readonly state: string;
+    /**
+     * Optional issuer returned by a provider authorization response.
+     */
+    readonly responseIssuer?: string;
+}
+/**
+ * Input accepted by {@link OidcFlow.callback}.
+ */
+export type OidcFlowCallbackInput = (OidcFlowCallbackBase & {
+    /**
+     * Provides the provider code.
+     */ readonly code: string;
+    /**
+     * Excludes provider error.
+     */ readonly error?: never;
+}) | (OidcFlowCallbackBase & {
+    /**
+     * Provides the provider error.
+     */ readonly error: string;
+    /**
+     * Excludes provider code.
+     */ readonly code?: never;
+});
+/**
+ * Result of atomically consuming an authorization-code transaction.
+ */
+export type OidcFlowCallbackResult = {
+    /**
+     * Identifies an accepted callback.
+     */
+    readonly kind: "granted";
+    /**
+     * Provides the one-time application grant.
+     */
+    readonly grant: string;
+    /**
+     * Provides the permitted post-login redirect.
+     */
+    readonly postLoginRedirect: string;
+    /**
+     * Provides grant expiry milliseconds.
+     */
+    readonly expiresAt: number;
+} | {
+    /**
+     * Identifies a rejected callback.
+     */
+    readonly kind: "rejected";
+    /**
+     * Explains why the callback was rejected.
+     */
+    readonly reason: "invalid-input" | "not-found" | "expired" | "provider-error" | "issuer-mismatch" | "verification-failed" | "mapping-failed" | "capacity-exceeded" | "entropy-exhausted" | "clock-failure" | "closed";
+};
+/**
+ * Input accepted by {@link OidcFlow.exchange}.
+ */
+export interface OidcFlowExchangeInput {
+    /**
+     * One-time grant returned by {@link OidcFlow.callback}.
+     */
+    readonly grant: string;
+    /**
+     * Browser-held RFC 7636 verifier for the application's separate grant.
+     */
+    readonly browserCodeVerifier: string;
+}
+/**
+ * Enumeration-safe result of a one-time application-session exchange.
+ */
+export type OidcFlowExchangeResult = {
+    /**
+     * Identifies an issued application session.
+     */
+    readonly kind: "issued";
+    /**
+     * Provides the issued application credential.
+     */
+    readonly credential: RequestCredential;
+    /**
+     * Provides the issued application session.
+     */
+    readonly session: ResolvedSession;
+} | {
+    /**
+     * Identifies a rejected exchange.
+     */
+    readonly kind: "rejected";
+};
+//# sourceMappingURL=contracts.d.ts.map

package/dist/oidc/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/oidc/contracts.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9F;;GAEG;AACH,MAAM,WAAW,aAAa;IAG5B;;;OAGG;IACH,GAAG,IAAI,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAG/B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAG1C;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAG9B;;;;;OAKG;IACH,OAAO,CACL,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAG5C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAG3C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,yBAAyB,CACvB,KAAK,EAAE,6BAA6B,GACnC,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IAGtC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IAGvC;;;;;OAKG;IACH,KAAK,CACH,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAG9B;;OAEG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,yBAAyB,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAC;IAEhD;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,wBAAwB,CAAC;IAEjD;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,4BAA4B,CAAC,EAAE,MAAM,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAGjC;;OAEG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAGE;;OAEG,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAE7B;;OAEG,CAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAEtC;;OAEG,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAChC,GACD;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EACb,eAAe,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,eAAe,GAAG,QAAQ,CAAC;CAC5F,CAAC;AAEN;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,CAAC,oBAAoB,GAAG;IAGtB;;OAEG,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE1B;;OAEG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CAC5B,CAAC,GACF,CAAC,oBAAoB,GAAG;IAGtB;;OAEG,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAE3B;;OAEG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;CAC3B,CAAC,CAAC;AAEP;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GACD;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EACX,eAAe,GACf,WAAW,GACX,SAAS,GACT,gBAAgB,GAChB,iBAAiB,GACjB,qBAAqB,GACrB,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,GACnB,eAAe,GACf,QAAQ,CAAC;CACd,CAAC;AAEN;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAGpC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC,GACD;IAGE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B,CAAC"}

package/dist/oidc/contracts.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/oidc/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/oidc/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/oidc/index.d.ts

@@ -0,0 +1,41 @@
+import type { OidcFlowCallbackInput, OidcFlowCallbackResult, OidcFlowExchangeInput, OidcFlowExchangeResult, OidcFlowOptions, OidcFlowStartInput, OidcFlowStartResult } from "./contracts.js";
+export type * from "./contracts.js";
+/**
+ * Bounded, framework-neutral authorization-code transaction manager.
+ *
+ * It owns finite start, callback, and one-time application-session exchange
+ * transitions; HTTP endpoints and provider discovery remain application work.
+ */
+export declare class OidcFlow {
+    #private;
+    /**
+     * Creates a bounded authorization-code flow.
+     * @param options The trusted provider, callback, transaction, grant, and session settings.
+     */
+    constructor(options: OidcFlowOptions);
+    /**
+     * Starts one finite authorization-code transaction without exposing any application credential.
+     * @param input The browser redirect and requested scopes.
+     * @returns The authorization URL and state, or a rejection.
+     */
+    start(input: OidcFlowStartInput): OidcFlowStartResult;
+    /**
+     * Processes a callback state before provider verification or mapping.
+     * A rejected callback never restores its transaction.
+     * @param input The callback state and provider response.
+     * @returns The callback result, including a one-time grant when accepted.
+     */
+    callback(input: OidcFlowCallbackInput): Promise<OidcFlowCallbackResult>;
+    /**
+     * Processes a grant before validating browser PKCE proof or issuing a session.
+     * All failures deliberately have the same result to avoid grant-state enumeration.
+     * @param input The grant and browser PKCE proof.
+     * @returns The issued application session or an enumeration-safe rejection.
+     */
+    exchange(input: OidcFlowExchangeInput): Promise<OidcFlowExchangeResult>;
+    /**
+     * Closes the flow and discards retained OIDC transaction material.
+     */
+    close(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/oidc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oidc/index.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAKV,qBAAqB,EACrB,sBAAsB,EAEtB,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,EAEf,kBAAkB,EAClB,mBAAmB,EAGpB,MAAM,gBAAgB,CAAC;AAExB,mBAAmB,gBAAgB,CAAC;AAapC;;;;;GAKG;AACH,qBAAa,QAAQ;;IAwBnB;;;OAGG;gBACS,OAAO,EAAE,eAAe;IAyDpC;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB;IA4DrD;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAqF7E;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAuC7E;;OAEG;IACH,KAAK,IAAI,IAAI;CAqKd"}