@mcp-abap-adt/auth-broker 4.0.0 → 5.0.0

package/dist/bindingOf.js

@@ -7,47 +7,77 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.destinationBinding = destinationBinding;
+exports.consumerRow = consumerRow;
 exports.bindingOf = bindingOf;
 const binding_1 = require("./binding");
 const destinations_1 = require("./destinations");
 /**
- * The binding of a `jwt` or `saml` destination with the grant it states: the
- * UAA grants and `saml2_bearer` by `uaaUrl` and the client, the OIDC grants by
- * the issuer and the client, `saml2_pure` by its ACS, and `none` by what the
- * means state.
+ * The binding of a `jwt` or `saml` destination with the grant it states — a
+ * pair of the closed list, checked before (`statedGrant`): the UAA grants,
+ * the OIDC grants, `saml2_pure`, `saml2_bearer` and `none`, each with the
+ * fields of its row. `certificate` is the certificate client the build
+ * read for the `clientAuthentication` strategy, or `null` when it read none.
  */
-function destinationBinding(authType, grant, means, client) {
+function destinationBinding(authType, grant, means, client, certificate = null) {
     if (grant === 'none')
         return (0, binding_1.handedOverBinding)(authType, means, client);
-    if ((0, destinations_1.isOidcGrant)(grant))
-        return (0, binding_1.oidcBinding)(means, client);
+    if ((0, destinations_1.isOidcGrant)(grant)) {
+        return (0, binding_1.oidcBinding)(grant, means, client, certificate);
+    }
     if (grant === 'saml2_pure')
         return (0, binding_1.samlPureBinding)(means);
-    return (0, binding_1.uaaBinding)(means, client);
+    if (grant === 'saml2_bearer') {
+        return (0, binding_1.samlBearerBinding)(means, client, certificate);
+    }
+    return (0, binding_1.uaaBinding)(grant, means, client, certificate);
+}
+/**
+ * The row of the token API's consumer provider: `provider/<authType>/<grant>`
+ * when the means state a pair of the closed list, else `provider/-`.
+ */
+function consumerRow(means) {
+    const authType = means?.authType;
+    const grant = means?.grantType;
+    return (0, destinations_1.isStatedRow)(authType, grant)
+        ? `provider/${authType}/${grant}`
+        : 'provider/-';
 }
 /**
  * The binding the broker writes beside a secret for a destination with these
- * means and this client — canonical, exactly what `getProvider` compares a
- * stored secret against. For a consumer that hands over a credential the
- * broker cannot obtain (a `none` destination: a token or cookies it was
- * given) and writes it to the session store itself: written with this binding,
- * `getProvider` presents it; written with any other, it refuses.
+ * means and this client: `issuedFor` the canonical resource, `issuedBy` the
+ * version-2 record of the row the means state, built from `means` and
+ * `client` alone.
+ *
+ * It is exactly what `getProvider` compares for a `none` row — its use: a
+ * consumer that hands over a credential the broker cannot obtain (a token or
+ * cookies it was given) writes it with this binding, and `getProvider`
+ * presents it; written with any other — a 4.x `bindingOf`'s included — it
+ * refuses. It is also exactly what `getProvider` writes for a token row built
+ * without a `clientAuthentication` strategy.
+ *
+ * It is **not** what a token row writes beside a `clientAuthentication`
+ * strategy: there the row's record also holds what the build read of the
+ * certificate client — its `certUrl`, and its certificate in the trust
+ * digest — and its client identity may be the certificate client's, none of
+ * which `bindingOf` is given. Nor is it the token API's record for a
+ * consumer's provider (`provider/…`).
  *
  * `means` are the key store's (`authType`, `grantType`, `serviceUrl`,
- * `sapClient`, the issuer or ACS); `client` is the key store's client, when the
- * destination has one. A destination that states no `jwt` / `saml` type or no
- * grant binds nothing: `{}`. Never logs, never throws.
+ * `sapClient`, the addresses and trust the row reads); `client` is the key
+ * store's client, when the destination has one. A destination that states no
+ * `jwt` / `saml` type, no grant, or a pair outside the closed list binds
+ * nothing: `{}`. Never logs, never throws.
  */
 function bindingOf(means, client = null) {
     const authType = means.authType;
     const grant = means.grantType;
-    if ((authType !== 'jwt' && authType !== 'saml') || !grant)
+    if (authType !== 'jwt' && authType !== 'saml')
+        return {};
+    if (!(0, destinations_1.isStatedRow)(authType, grant))
         return {};
     const { issuedFor, issuedBy } = destinationBinding(authType, grant, means, client);
-    const binding = {};
+    const binding = { issuedBy };
     if (issuedFor !== undefined)
         binding.issuedFor = issuedFor;
-    if (issuedBy !== undefined)
-        binding.issuedBy = issuedBy;
     return binding;
 }

package/dist/buildIdentity.d.ts

@@ -0,0 +1,137 @@
+/**
+ * A build's identity: everything the build read to make its provider.
+ *
+ * A provider is never changed: the broker hands out the provider it built
+ * while nothing that build read has changed, and builds a new one — which
+ * starts with nothing — the moment anything has. "What the build read" is
+ * recorded by the build itself, through one recording accessor
+ * (`IdentityRecorder`): every store answer a build takes — the means, the
+ * client, the certificate client, and on the consumer path the session's
+ * connection and client — is handed to the builders behind a proxy that notes
+ * each field read, as given. So the set of fields is each row's own, decided
+ * by the code that builds it, and cannot drift from it: a field a builder
+ * starts to read is part of the identity from then on.
+ *
+ * Every call re-reads the same sources (`StoreReads`, each at most once per
+ * call) and compares each recorded field exactly (`BuildIdentity.unchanged`):
+ * strings, numbers and booleans by `Object.is` — an absent value is distinct
+ * from `''` — arrays and plain objects element by element.
+ *
+ * Secrets take part here only: a password, a client secret, a key, a subject
+ * token the build read are held in memory beside the provider, which holds
+ * them anyway. The identity is never logged, never persisted, and never
+ * hashed into anything persisted; what a session file holds is the binding
+ * record (`binding.ts`), which holds no secret.
+ */
+/** The store answers a build may read. */
+export type SourceName = 
+/** The key store's connection config: the means. */
+'means'
+/** The key store's authorization config: the secret client. */
+ | 'client'
+/** The key store's certificate client. */
+ | 'certificate'
+/** The session store's connection config (the consumer path). */
+ | 'sessionConnection'
+/** The session store's authorization config (the consumer path). */
+ | 'sessionClient';
+/** Reads one source from its store: an object, or `null` for none. */
+export type SourceReader = (name: SourceName) => Promise<object | null>;
+/**
+ * The error for a store answer whose `field` the broker cannot take — a
+ * function, a symbol, a getter that throws: a configuration fault naming the
+ * field, never its value.
+ */
+export type ShapeRefusal = (field: string) => unknown;
+/**
+ * The sources of one call, each read from its store at most once: the
+ * comparison with the cached build and — when that finds a change — the new
+ * build read the same answers.
+ */
+export declare class StoreReads {
+    private readonly reader;
+    private readonly refuse;
+    private readonly answers;
+    /**
+     * @param refuse The error for a field of a shape the broker cannot take.
+     */
+    constructor(reader: SourceReader, refuse: ShapeRefusal);
+    read(name: SourceName): Promise<object | null>;
+}
+/** One fact a build read. */
+type Entry = {
+    readonly source: SourceName;
+    readonly kind: 'answer';
+    readonly value: 'none' | 'some' | 'failed';
+} | {
+    readonly source: SourceName;
+    readonly kind: 'get';
+    readonly field: string;
+    readonly value: unknown;
+} | {
+    readonly source: SourceName;
+    readonly kind: 'has';
+    readonly field: string;
+    readonly value: boolean;
+} | {
+    readonly source: SourceName;
+    readonly kind: 'keys';
+    readonly value: readonly string[];
+} | {
+    readonly kind: 'derived';
+    readonly value: unknown;
+    readonly derive: (reads: StoreReads) => Promise<unknown>;
+};
+/**
+ * Exact equality of two values as read: `Object.is` for everything but arrays
+ * and plain objects, which are equal element by element (and key by key).
+ */
+export declare function sameValue(a: unknown, b: unknown): boolean;
+/**
+ * The one recording accessor of a build: every source the build reads goes
+ * through `read`, and every field read of what it answers — a property read,
+ * an `in` test, an enumeration — is noted, once, as given. `seal()` ends the
+ * recording: what is read afterwards is not the build's.
+ */
+export declare class IdentityRecorder {
+    readonly reads: StoreReads;
+    private readonly entries;
+    private readonly noted;
+    private sealed;
+    /** @param reads The call's reads, which every recorded source goes through. */
+    constructor(reads: StoreReads);
+    /**
+     * The source's answer, behind the recording proxy, or `null`. A read that
+     * fails is noted as failed and rethrown.
+     */
+    read<T extends object>(name: SourceName): Promise<T | null>;
+    /**
+     * Notes a value the build derived from sources it reads without the
+     * recording proxy, with how to derive it again from a later call's reads.
+     * For sources whose answers change for reasons that are no change of the
+     * means — the session store's, which the broker's own writes change: the
+     * identity is what the build took from them, never what else they hold.
+     */
+    derived(value: unknown, derive: (reads: StoreReads) => Promise<unknown>): void;
+    /** The identity as read so far; nothing read later is recorded. */
+    seal(): BuildIdentity;
+    private note;
+    private watched;
+}
+/**
+ * What one build read, sealed: compared with a fresh read of the same
+ * sources on every call. Holds secrets the build read, in memory only.
+ */
+export declare class BuildIdentity {
+    private readonly entries;
+    constructor(entries: readonly Entry[]);
+    /**
+     * Whether every fact this build read is still what the stores answer —
+     * each source re-read through `reads` (once per call), each field compared
+     * exactly. A source that cannot be read now, where it could then, is a
+     * change: the new build meets the failure itself.
+     */
+    unchanged(reads: StoreReads): Promise<boolean>;
+}
+export {};
+//# sourceMappingURL=buildIdentity.d.ts.map

package/dist/buildIdentity.d.ts.map

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

package/dist/buildIdentity.js

@@ -0,0 +1,393 @@
+"use strict";
+/**
+ * A build's identity: everything the build read to make its provider.
+ *
+ * A provider is never changed: the broker hands out the provider it built
+ * while nothing that build read has changed, and builds a new one — which
+ * starts with nothing — the moment anything has. "What the build read" is
+ * recorded by the build itself, through one recording accessor
+ * (`IdentityRecorder`): every store answer a build takes — the means, the
+ * client, the certificate client, and on the consumer path the session's
+ * connection and client — is handed to the builders behind a proxy that notes
+ * each field read, as given. So the set of fields is each row's own, decided
+ * by the code that builds it, and cannot drift from it: a field a builder
+ * starts to read is part of the identity from then on.
+ *
+ * Every call re-reads the same sources (`StoreReads`, each at most once per
+ * call) and compares each recorded field exactly (`BuildIdentity.unchanged`):
+ * strings, numbers and booleans by `Object.is` — an absent value is distinct
+ * from `''` — arrays and plain objects element by element.
+ *
+ * Secrets take part here only: a password, a client secret, a key, a subject
+ * token the build read are held in memory beside the provider, which holds
+ * them anyway. The identity is never logged, never persisted, and never
+ * hashed into anything persisted; what a session file holds is the binding
+ * record (`binding.ts`), which holds no secret.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BuildIdentity = exports.IdentityRecorder = exports.StoreReads = void 0;
+exports.sameValue = sameValue;
+/** `IConnectionConfig`'s fields (interfaces-auth-broker). */
+const CONNECTION_FIELDS = [
+    'serviceUrl',
+    'authorizationToken',
+    'username',
+    'password',
+    'authType',
+    'grantType',
+    'expiresAt',
+    'issuedFor',
+    'issuedBy',
+    'sapClient',
+    'language',
+    'sessionCookies',
+    'sncPartnerName',
+    'sncQop',
+    'sncLib',
+    'sncMyName',
+    'oidcIssuerUrl',
+    'oidcAuthorizationEndpoint',
+    'oidcTokenEndpoint',
+    'oidcDeviceAuthorizationEndpoint',
+    'oidcScopes',
+    'oidcSubjectToken',
+    'oidcSubjectTokenType',
+    'oidcAudience',
+    'oidcActorToken',
+    'oidcActorTokenType',
+    'samlIdpSsoUrl',
+    'samlIdpEntityId',
+    'samlIdpCertificates',
+    'samlSpEntityId',
+    'samlAcsUrl',
+    'samlRelayState',
+    'samlIdpInitiated',
+    'samlClockSkewMs',
+    'samlTokenUrl',
+];
+/** `IAuthorizationConfig`'s fields (interfaces-auth-sap). */
+const AUTHORIZATION_FIELDS = [
+    'uaaUrl',
+    'uaaClientId',
+    'uaaClientSecret',
+    'refreshToken',
+];
+/** `IClientCertificate`'s fields (interfaces-auth-broker). */
+const CERTIFICATE_FIELDS = [
+    'uaaUrl',
+    'clientId',
+    'certificate',
+    'key',
+    'certUrl',
+];
+/** The contract each source answers, by its fields. */
+const CONTRACT_FIELDS = {
+    means: CONNECTION_FIELDS,
+    sessionConnection: CONNECTION_FIELDS,
+    client: AUTHORIZATION_FIELDS,
+    sessionClient: AUTHORIZATION_FIELDS,
+    certificate: CERTIFICATE_FIELDS,
+};
+/**
+ * The sources of one call, each read from its store at most once: the
+ * comparison with the cached build and — when that finds a change — the new
+ * build read the same answers.
+ */
+class StoreReads {
+    reader;
+    refuse;
+    answers = new Map();
+    /**
+     * @param refuse The error for a field of a shape the broker cannot take.
+     */
+    constructor(reader, refuse) {
+        this.reader = reader;
+        this.refuse = refuse;
+    }
+    read(name) {
+        let answer = this.answers.get(name);
+        if (!answer) {
+            // One snapshot per answer: what the builders hand their providers and
+            // what the identity records are the same values, and a store that
+            // changes its object afterwards — in place — changes neither.
+            answer = Promise.resolve()
+                .then(() => this.reader(name))
+                .then((value) => snapshot(name, value, this.refuse));
+            // Read by whoever asks; a failure is theirs to see, not an unhandled
+            // rejection of the memo.
+            answer.catch(() => { });
+            this.answers.set(name, answer);
+        }
+        return answer;
+    }
+}
+exports.StoreReads = StoreReads;
+/**
+ * Properties a promise or a serialiser looks up on any object — awaiting an
+ * answer reads its `then` — which are no field a build reads: never noted.
+ */
+const NOT_FIELDS = new Set(['then', 'toJSON']);
+/**
+ * A store answer as the broker uses it: a fresh, frozen plain object holding
+ * the contract's fields of the source, each read through the answer by plain
+ * property access — own or inherited, a field or a getter, whatever the
+ * answer's prototype — and copied deeply: arrays element by element, nested
+ * objects field by field. The store's own object is never handed on, so
+ * nothing the store does to it later reaches a provider built from it. A
+ * field of a shape the broker cannot take is refused naming it.
+ */
+function snapshot(name, answer, refuse) {
+    if (answer === null || answer === undefined)
+        return null;
+    if (typeof answer !== 'object')
+        throw refuse(name);
+    const copy = {};
+    for (const field of CONTRACT_FIELDS[name]) {
+        let value;
+        try {
+            value = answer[field];
+        }
+        catch {
+            throw refuse(field);
+        }
+        if (value === undefined)
+            continue;
+        copy[field] = snapshotValue(value, field, refuse, new Set());
+    }
+    return Object.freeze(copy);
+}
+/** One value of a field, copied deeply and frozen; refused when it cannot be. */
+function snapshotValue(value, field, refuse, seen) {
+    if (value === null)
+        return null;
+    switch (typeof value) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+        case 'bigint':
+        case 'undefined':
+            return value;
+        case 'object':
+            break;
+        default:
+            // A function or a symbol.
+            throw refuse(field);
+    }
+    const object = value;
+    if (seen.has(object))
+        throw refuse(field);
+    seen.add(object);
+    try {
+        if (Array.isArray(object)) {
+            const length = object.length;
+            const copy = [];
+            for (let i = 0; i < length; i += 1) {
+                copy.push(snapshotValue(object[i], field, refuse, seen));
+            }
+            return Object.freeze(copy);
+        }
+        const copy = {};
+        for (const key of Object.keys(object)) {
+            copy[key] = snapshotValue(object[key], field, refuse, seen);
+        }
+        return Object.freeze(copy);
+    }
+    catch {
+        // A getter or a proxy that threw inside the value, or a part of it of a
+        // shape the broker cannot take: the field's fault, whatever was thrown.
+        throw refuse(field);
+    }
+    finally {
+        seen.delete(object);
+    }
+}
+/** A copy of a value as read: arrays and plain objects copied, element by element. */
+function copied(value) {
+    if (Array.isArray(value))
+        return value.map(copied);
+    if (isPlainObject(value)) {
+        const copy = {};
+        for (const key of Object.keys(value))
+            copy[key] = copied(value[key]);
+        return copy;
+    }
+    return value;
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Exact equality of two values as read: `Object.is` for everything but arrays
+ * and plain objects, which are equal element by element (and key by key).
+ */
+function sameValue(a, b) {
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+            return false;
+        }
+        return a.every((element, i) => sameValue(element, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const keys = Object.keys(a).sort();
+        const others = Object.keys(b).sort();
+        if (!sameValue(keys, others))
+            return false;
+        return keys.every((key) => sameValue(a[key], b[key]));
+    }
+    return Object.is(a, b);
+}
+/** The own string keys of an answer, in a fixed order. */
+function keysOf(target) {
+    return Object.keys(target).sort();
+}
+/**
+ * The one recording accessor of a build: every source the build reads goes
+ * through `read`, and every field read of what it answers — a property read,
+ * an `in` test, an enumeration — is noted, once, as given. `seal()` ends the
+ * recording: what is read afterwards is not the build's.
+ */
+class IdentityRecorder {
+    reads;
+    entries = [];
+    noted = new Set();
+    sealed = false;
+    /** @param reads The call's reads, which every recorded source goes through. */
+    constructor(reads) {
+        this.reads = reads;
+    }
+    /**
+     * The source's answer, behind the recording proxy, or `null`. A read that
+     * fails is noted as failed and rethrown.
+     */
+    async read(name) {
+        let answer;
+        try {
+            answer = await this.reads.read(name);
+        }
+        catch (error) {
+            this.note(`${name}`, { source: name, kind: 'answer', value: 'failed' });
+            throw error;
+        }
+        this.note(`${name}`, {
+            source: name,
+            kind: 'answer',
+            value: answer ? 'some' : 'none',
+        });
+        return answer ? this.watched(name, answer) : null;
+    }
+    /**
+     * Notes a value the build derived from sources it reads without the
+     * recording proxy, with how to derive it again from a later call's reads.
+     * For sources whose answers change for reasons that are no change of the
+     * means — the session store's, which the broker's own writes change: the
+     * identity is what the build took from them, never what else they hold.
+     */
+    derived(value, derive) {
+        if (this.sealed)
+            return;
+        this.entries.push({ kind: 'derived', value: copied(value), derive });
+    }
+    /** The identity as read so far; nothing read later is recorded. */
+    seal() {
+        this.sealed = true;
+        return new BuildIdentity([...this.entries]);
+    }
+    note(key, entry) {
+        if (this.sealed || this.noted.has(key))
+            return;
+        this.noted.add(key);
+        this.entries.push(entry);
+    }
+    watched(source, target) {
+        return new Proxy(target, {
+            get: (object, property) => {
+                const value = Reflect.get(object, property);
+                if (typeof property === 'string' && !NOT_FIELDS.has(property)) {
+                    this.note(`${source}.get.${property}`, {
+                        source,
+                        kind: 'get',
+                        field: property,
+                        value: copied(value),
+                    });
+                }
+                return value;
+            },
+            has: (object, property) => {
+                const value = Reflect.has(object, property);
+                if (typeof property === 'string' && !NOT_FIELDS.has(property)) {
+                    this.note(`${source}.has.${property}`, {
+                        source,
+                        kind: 'has',
+                        field: property,
+                        value,
+                    });
+                }
+                return value;
+            },
+            ownKeys: (object) => {
+                this.note(`${source}.keys`, {
+                    source,
+                    kind: 'keys',
+                    value: keysOf(object),
+                });
+                return Reflect.ownKeys(object);
+            },
+        });
+    }
+}
+exports.IdentityRecorder = IdentityRecorder;
+/**
+ * What one build read, sealed: compared with a fresh read of the same
+ * sources on every call. Holds secrets the build read, in memory only.
+ */
+class BuildIdentity {
+    entries;
+    constructor(entries) {
+        this.entries = entries;
+    }
+    /**
+     * Whether every fact this build read is still what the stores answer —
+     * each source re-read through `reads` (once per call), each field compared
+     * exactly. A source that cannot be read now, where it could then, is a
+     * change: the new build meets the failure itself.
+     */
+    async unchanged(reads) {
+        const answers = new Map();
+        for (const entry of this.entries) {
+            if (entry.kind === 'derived') {
+                const now = await entry.derive(reads).then((value) => ({ value }), () => undefined);
+                if (!now || !sameValue(entry.value, now.value))
+                    return false;
+                continue;
+            }
+            let answer = answers.get(entry.source);
+            if (answer === undefined) {
+                answer = await reads.read(entry.source).then((value) => value, () => 'failed');
+                answers.set(entry.source, answer);
+            }
+            if (!sameFact(entry, answer))
+                return false;
+        }
+        return true;
+    }
+}
+exports.BuildIdentity = BuildIdentity;
+function sameFact(entry, answer) {
+    if (entry.kind === 'answer') {
+        const now = answer === 'failed' ? 'failed' : answer ? 'some' : 'none';
+        return entry.value === now;
+    }
+    if (answer === null || answer === 'failed')
+        return false;
+    switch (entry.kind) {
+        case 'get':
+            return sameValue(entry.value, Reflect.get(answer, entry.field));
+        case 'has':
+            return entry.value === Reflect.has(answer, entry.field);
+        case 'keys':
+            return sameValue(entry.value, keysOf(answer));
+    }
+}