@spine-event-engine/auth 2.0.0-snapshot.26 → 2.0.0-snapshot.28

package/dist/oidc/flow-store.js

@@ -0,0 +1,184 @@
+/*
+ * 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.
+ */
+import { clone, equals } from "@bufbuild/protobuf";
+import { OidcLoginGrantSchema, OidcLoginTransactionSchema, } from "@spine-event-engine/proto/auth";
+import { OidcFlowKeys } from "./records.js";
+import { SessionRecords } from "../sessions/session-record.js";
+/**
+ * Process-local atomic transitions for one component login flow.
+ */
+export class MemoryOidcFlowStore {
+    /**
+     * Flow identity used in this process-local record family.
+     */
+    flowId;
+    #transactions = new Map();
+    #grants = new Map();
+    #clock;
+    #maxTransactions;
+    #maxGrants;
+    #closed = false;
+    /**
+     * Binds a flow identity, trusted clock and process-local capacity policy.
+     *
+     * @param flowId Identity qualifying all state and grant digests.
+     * @param clock Latest allowed maintenance cutoff.
+     * @param maxTransactions Existing memory transaction bound.
+     * @param maxGrants Existing memory grant bound.
+     */
+    constructor(flowId, clock, maxTransactions, maxGrants) {
+        if (!flowId ||
+            !Number.isSafeInteger(maxTransactions) ||
+            maxTransactions <= 0 ||
+            !Number.isSafeInteger(maxGrants) ||
+            maxGrants <= 0)
+            throw new TypeError("Invalid process-local OIDC flow configuration.");
+        this.flowId = flowId;
+        this.#clock = clock;
+        this.#maxTransactions = maxTransactions;
+        this.#maxGrants = maxGrants;
+    }
+    /**
+     * Checks current process-local transaction capacity.
+     *
+     * @returns Whether another transaction needs explicit maintenance.
+     */
+    transactionsFull() {
+        return this.#transactions.size >= this.#maxTransactions;
+    }
+    /**
+     * Checks current process-local grant capacity.
+     *
+     * @returns Whether another grant needs explicit maintenance.
+     */
+    grantsFull() {
+        return this.#grants.size >= this.#maxGrants;
+    }
+    /**
+     * @inheritdoc
+     */
+    insertTransaction(record, signal) {
+        this.#check(record, signal);
+        if (this.transactionsFull() || this.#transactions.has(record.lookupDigest))
+            return Promise.resolve(false);
+        this.#transactions.set(record.lookupDigest, clone(OidcLoginTransactionSchema, record));
+        return Promise.resolve(true);
+    }
+    /**
+     * @inheritdoc
+     */
+    readTransaction(digest, signal) {
+        this.#check(undefined, signal);
+        const record = this.#transactions.get(digest);
+        return Promise.resolve(record === undefined ? undefined : clone(OidcLoginTransactionSchema, record));
+    }
+    /**
+     * @inheritdoc
+     */
+    consumeTransaction(expected, signal) {
+        this.#check(expected, signal);
+        const current = this.#transactions.get(expected.lookupDigest);
+        if (current === undefined || !equals(OidcLoginTransactionSchema, current, expected))
+            return Promise.resolve(false);
+        this.#transactions.delete(expected.lookupDigest);
+        return Promise.resolve(true);
+    }
+    /**
+     * @inheritdoc
+     */
+    insertGrant(record, signal) {
+        this.#check(record, signal);
+        if (this.grantsFull() || this.#grants.has(record.lookupDigest))
+            return Promise.resolve(false);
+        this.#grants.set(record.lookupDigest, clone(OidcLoginGrantSchema, record));
+        return Promise.resolve(true);
+    }
+    /**
+     * @inheritdoc
+     */
+    readGrant(digest, signal) {
+        this.#check(undefined, signal);
+        const record = this.#grants.get(digest);
+        return Promise.resolve(record === undefined ? undefined : clone(OidcLoginGrantSchema, record));
+    }
+    /**
+     * @inheritdoc
+     */
+    consumeGrant(expected, signal) {
+        this.#check(expected, signal);
+        const current = this.#grants.get(expected.lookupDigest);
+        if (current === undefined || !equals(OidcLoginGrantSchema, current, expected))
+            return Promise.resolve(false);
+        this.#grants.delete(expected.lookupDigest);
+        return Promise.resolve(true);
+    }
+    /**
+     * @inheritdoc
+     */
+    purgeExpired(cutoff, signal) {
+        this.#check(undefined, signal);
+        const valid = SessionRecords.deadline(cutoff);
+        if (SessionRecords.compare(valid, SessionRecords.deadline(this.#clock())) > 0)
+            throw new RangeError("Purge cutoff cannot be later than the trusted clock.");
+        const transactions = this.#purge(this.#transactions, valid, signal);
+        const grants = this.#purge(this.#grants, valid, signal);
+        return Promise.resolve({ transactions, grants });
+    }
+    /**
+     * @inheritdoc
+     */
+    close() {
+        this.#closed = true;
+        this.#transactions.clear();
+        this.#grants.clear();
+        return Promise.resolve();
+    }
+    /**
+     * Checks lifecycle, cancellation and flow binding.
+     *
+     * @param record Optional record being mutated.
+     * @param signal Optional cancellation.
+     */
+    #check(record, signal) {
+        if (this.#closed)
+            throw new Error("OIDC flow store is closed.");
+        signal?.throwIfAborted();
+        if (record !== undefined) {
+            if (record.flowId !== this.flowId)
+                throw new TypeError("OIDC flow identity differs.");
+            OidcFlowKeys.expiry(record);
+        }
+    }
+    /**
+     * Removes expired records from one local family.
+     *
+     * @typeParam R Transaction or grant record.
+     * @param records Selected local family.
+     * @param cutoff Trusted maximum deadline.
+     * @param signal Optional cancellation.
+     * @returns Number removed in this invocation.
+     */
+    #purge(records, cutoff, signal) {
+        let removed = 0;
+        for (const [key, record] of records) {
+            signal?.throwIfAborted();
+            if (SessionRecords.compare(OidcFlowKeys.expiry(record), cutoff) <= 0) {
+                records.delete(key);
+                removed += 1;
+            }
+        }
+        return removed;
+    }
+}
+//# sourceMappingURL=flow-store.js.map

package/dist/oidc/flow-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-store.js","sourceRoot":"","sources":["../../src/oidc/flow-store.ts"],"names":[],"mappings":"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"}

package/dist/oidc/index.d.ts

@@ -1,9 +1,10 @@
+import { type Timestamp } from "@bufbuild/protobuf/wkt";
 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
+ * It manages finite start, callback, and one-time application-session exchange
  * transitions; HTTP endpoints and provider discovery remain application work.
  */
 export declare class OidcFlow {
@@ -15,27 +16,46 @@ export declare class OidcFlow {
     constructor(options: OidcFlowOptions);
     /**
      * Starts one finite authorization-code transaction without exposing any application credential.
-     * @param input The browser redirect and requested scopes.
+     * @param input The browser challenge and post-login redirect.
+     * @param signal Optional host request cancellation; ordinary abort rejects with its reason.
      * @returns The authorization URL and state, or a rejection.
      */
-    start(input: OidcFlowStartInput): OidcFlowStartResult;
+    start(input: OidcFlowStartInput, signal?: AbortSignal): Promise<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.
+     * @param signal Optional host request cancellation; a consumed state remains consumed.
      * @returns The callback result, including a one-time grant when accepted.
      */
-    callback(input: OidcFlowCallbackInput): Promise<OidcFlowCallbackResult>;
+    callback(input: OidcFlowCallbackInput, signal?: AbortSignal): 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.
+     * Validates and consumes a grant before issuing an application session.
+     * All failures deliberately have the same result to avoid grant enumeration.
      * @param input The grant and browser PKCE proof.
+     * @param signal Optional host request cancellation; a consumed grant remains consumed.
      * @returns The issued application session or an enumeration-safe rejection.
      */
-    exchange(input: OidcFlowExchangeInput): Promise<OidcFlowExchangeResult>;
+    exchange(input: OidcFlowExchangeInput, signal?: AbortSignal): Promise<OidcFlowExchangeResult>;
     /**
-     * Closes the flow and discards retained OIDC transaction material.
+     * Closes the flow after admitted work and original collaborator promises settle.
+     *
+     * An injected store and factory remain open. A late distinct issuer failure
+     * rejects this close operation; repeated calls retain that result.
+     *
+     * @returns Completion after raw work drains and local memory closes.
      */
-    close(): void;
+    close(): Promise<void>;
+    /**
+     * Removes eligible records through the selected flow store.
+     *
+     * @param cutoff Trusted current-or-earlier exact deadline.
+     * @param signal Optional cancellation.
+     * @returns Confirmed transaction and grant removals in this pass.
+     */
+    purgeExpired(cutoff: Timestamp, signal?: AbortSignal): Promise<{
+        transactions: number;
+        grants: number;
+    }>;
 }
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oidc/index.ts"],"names":[],"mappings":"AAoBA,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;;IA6CnB;;;OAGG;gBACS,OAAO,EAAE,eAAe;IAuBpC;;;;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;CA2Kd"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oidc/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAazE,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;;IAuDnB;;;OAGG;gBACS,OAAO,EAAE,eAAe;IAkDpC;;;;;OAKG;IACG,KAAK,CAAC,KAAK,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA0I1F;;;;;;OAMG;IACG,QAAQ,CACZ,KAAK,EAAE,qBAAqB,EAC5B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC;IA4QlC;;;;;;OAMG;IACG,QAAQ,CACZ,KAAK,EAAE,qBAAqB,EAC5B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC;IA0FlC;;;;;;;OAOG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAatB;;;;;;OAMG;IACH,YAAY,CACV,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CA2TrD"}