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

package/dist/binding.d.ts

@@ -1,95 +1,168 @@
 /**
- * A secret is bound to the resource it was obtained for and to who issued it.
+ * A secret is bound to the resource it was obtained for and to everything that
+ * decides where it goes and whose it is.
  *
- * The session store keeps two strings beside the secret — `issuedFor`, the
- * resource, and `issuedBy`, the issuer and its client — and the broker uses a
- * stored secret only when both equal what this destination's means give. The
- * store keeps them as given; the broker canonicalises **both sides** before it
- * compares, with the one function here (the broker's only, decided), so a store
- * need not canonicalise and a legacy file's composed URI compares equal.
+ * The session store keeps two strings beside the secret, and the broker uses a
+ * stored secret only when both equal what this destination's means give:
  *
- * The canonical URI:
- * - scheme and host lower-cased (by `URL`, for http and https);
- * - the port explicit — `443` for `https`, `80` for `http` when the URL has
- *   none; another scheme keeps the port it states;
- * - the path without a trailing `/` (the root path is empty), its case kept;
- * - one query parameter at most — `sap-client=<n>` for a resource,
- *   `client_id=<id>` for an issuer, none for a SAML ACS — parsed and
- *   re-encoded with `URLSearchParams`, so a value percent-encoded on one side
- *   and plain on the other compares equal;
- * - no user info, no other parameter, no fragment.
+ * - **`issuedFor`**, the resource: `serviceUrl` with the SAP client, in the
+ *   canonical form 4.x wrote (`resourceUri`). Both sides are canonicalised
+ *   before they are compared, so a stored value written by any 4.x-era
+ *   consumer compares equal.
+ * - **`issuedBy`**, a versioned record only the broker produces
+ *   (`bindingRecord`):
  *
- * A URL that does not parse, or has no host, has no canonical form: the
- * binding is then absent, never guessed.
+ *   ```
+ *   mcp-abap-adt-binding/2;<row>;<eleven address fields>;<trust>
+ *   ```
+ *
+ *   `row` is `authType/grantType` (or `provider/…` for the token API's
+ *   consumer provider); each address field is the exact string the row hands
+ *   its provider — `encodeURIComponent`-encoded, `""` when it hands none, never
+ *   canonicalised — in the fixed order of `RECORD_FIELDS`; `trust` is the
+ *   SHA-256 of the row's non-secret trust input (`trustDigest`), or `""`.
+ *   The record is compared by exact equality and never parsed, split or
+ *   matched; no regular expression touches it.
+ *
+ * No secret takes part in either string, nor a hash of one: a hash in a
+ * session file can be checked offline against guesses.
  */
 import type { IConfig, IConnectionConfig } from '@mcp-abap-adt/interfaces-auth-broker';
 import type { IAuthorizationConfig } from '@mcp-abap-adt/interfaces-auth-sap';
+/** What a binding reads of a client: who it is, never its secret. */
+export type BoundClient = Pick<IAuthorizationConfig, 'uaaUrl' | 'uaaClientId'>;
 /**
- * The resource: `serviceUrl` with the SAP client as `sap-client` — the
- * destination's `sapClient` when it states one, over a `sap-client` already in
- * the URL. For a stored value, call it without `sapClient`.
+ * The certificate client a build read for the `clientAuthentication`
+ * strategy, as the store answered it: where its token endpoint is, and its
+ * public certificate — never its key.
  */
-export declare function resourceUri(serviceUrl: unknown, sapClient?: string): string | undefined;
+export interface BoundCertificate {
+    readonly certUrl: unknown;
+    readonly certificate: unknown;
+}
+/** The eleven address fields of the record, in their fixed order. */
+export declare const RECORD_FIELDS: readonly ["clientId", "uaaUrl", "oidcIssuerUrl", "oidcTokenEndpoint", "oidcAuthorizationEndpoint", "oidcDeviceAuthorizationEndpoint", "oidcAudience", "samlIdpSsoUrl", "samlAcsUrl", "samlTokenUrl", "certUrl"];
+/** The address values a row hands its provider; any one may be absent. */
+export type RecordFields = Partial<Record<(typeof RECORD_FIELDS)[number], unknown>>;
+/**
+ * The `issuedBy` record: the version, the row, the eleven address fields in
+ * their fixed order — each the exact string, encoded, `""` when absent or
+ * `''` — and the trust digest. Every field is always present, and none holds
+ * `;`, so the string is unambiguous without being parsed.
+ */
+export declare function bindingRecord(row: string, fields: RecordFields, trust: string): string;
 /**
- * The issuer and its client: the authorization server's base URL with
- * `client_id`. For a stored value, call it without `clientId`.
+ * The trust digest: lower-case hex SHA-256 of the UTF-8 bytes of
+ * `"mcp-abap-adt-binding/2/trust\n"` and the JSON of the `[name, value]` pairs
+ * in the row's fixed order — no trimming, no canonicalisation. JSON of arrays
+ * and primitives has one output (lone surrogates escaped), so equal inputs
+ * give equal bytes.
  */
-export declare function issuerUri(issuerUrl: unknown, clientId?: string): string | undefined;
-/** The ACS of the system that set SAML session cookies: origin and path. */
-export declare function acsUri(acsUrl: unknown): string | undefined;
-/** How a stored `issuedBy` is read: as an issuer with its client, or as an ACS. */
-export type IssuerKind = 'issuer' | 'acs';
-/** What this destination's means bind a secret to, canonical; absent where they cannot say. */
+export declare function trustDigest(pairs: readonly (readonly [string, unknown])[]): string;
+/** What this destination's means bind a secret to. */
 export interface Binding {
-    issuedFor?: string;
-    issuedBy?: string;
-    /** How the stored `issuedBy` is canonicalised before it is compared. */
-    issuerKind: IssuerKind;
+    /** The canonical resource; absent when the means state none. */
+    issuedFor?: string | undefined;
+    /** The record: always present — at least the row. */
+    issuedBy: string;
+    /**
+     * The record holds the client the row authenticates and every server
+     * address its provider sends a credential to. Only such a
+     * binding is seeded from a stored session, or carries its refresh token.
+     */
+    fullyStated: boolean;
     /**
-     * The means state an issuer — for a `none` row, whether `issuedBy` is
-     * compared at all. True even when the stated URL does not parse: then it
-     * matches nothing.
+     * Set on the `clientAuthentication` strategy path only: a resource neither
+     * side states — no `issuedFor` computed and none stored — matches, so the
+     * record alone decides. A resource stated on one side only never matches.
      */
-    issuerStated: boolean;
+    unstatedResourceMatches?: true;
 }
 /**
- * The UAA grants (`authorization_code`, `client_credentials`, `passcode`) and
- * `saml2_bearer`, whose token UAA issues to its client: the resource, and `uaaUrl` with `uaaClientId` — both required to match.
+ * The canonical resource URI, as 4.x wrote it: scheme and host lower-cased
+ * (by `URL`, for http and https); the port explicit (`443` / `80` by
+ * default); the path without a trailing `/`, its case kept; one query
+ * parameter, `sap-client=<n>` — `sapClient` when given, else the one the URL
+ * carries — re-encoded with `URLSearchParams`; no user info, no other
+ * parameter, no fragment. A URL that does not parse, or has no host, has no
+ * canonical form: `undefined`, never guessed. For a stored value, call it
+ * without `sapClient`.
+ */
+export declare function resourceUri(serviceUrl: unknown, sapClient?: string): string | undefined;
+/**
+ * The UAA grants (`authorization_code`, `client_credentials`, `passcode`):
+ * the client id and `uaaUrl` as the provider receives them, and `certUrl`
+ * when the build read the certificate client; trust is the client
+ * certificate. Fully stated with the client, `uaaUrl` and — when read —
+ * `certUrl`.
  */
-export declare function uaaBinding(means: IConnectionConfig, client: IAuthorizationConfig | null): Binding;
+export declare function uaaBinding(grant: string, means: IConnectionConfig, client: BoundClient | null, certificate: BoundCertificate | null): Binding;
 /**
- * The OIDC grants: the resource, and the issuer — `oidcIssuerUrl`, else
- * `uaaUrl` — with `uaaClientId`; both required to match. Means that state
- * neither issuer (explicit endpoints alone) bind no stored secret: one is then
- * never seeded.
+ * The OIDC grants: the client id, `oidcIssuerUrl`, `oidcTokenEndpoint`, and
+ * the grant's own endpoint (`oidcAuthorizationEndpoint`,
+ * `oidcDeviceAuthorizationEndpoint`) or audience (`oidcAudience`), and
+ * `certUrl` when read; trust is the scopes, the `password` grant's
+ * `username`, the token-exchange token types, and the client certificate.
+ *
+ * Fully stated with the client, each endpoint the grant sends to — explicit,
+ * or the issuer it is discovered from — and `certUrl` when read;
+ * `token_exchange` never: its subject token, a secret, decides whose
+ * credential it obtains.
  */
-export declare function oidcBinding(means: IConnectionConfig, client: IAuthorizationConfig | null): Binding;
+export declare function oidcBinding(grant: string, means: IConnectionConfig, client: BoundClient | null, certificate: BoundCertificate | null): Binding;
 /**
- * `saml2_pure`: the resource, and the ACS of the system that sets the
- * cookies — `samlAcsUrl`, origin and path; both required to match.
+ * `saml2_pure`: the IdP's SSO URL and the ACS of the system that sets the
+ * cookies; trust is the SAML trust. Fully stated with both.
  */
 export declare function samlPureBinding(means: IConnectionConfig): Binding;
 /**
- * The token API with a consumer's provider: what the broker handed
- * that provider — the `serviceUrl` it resolved, with the SAP client, and for a
- * factory the client it resolved (`uaaUrl` with `uaaClientId`). An instance is
- * handed no client, so no issuer is claimed for what it obtains: `issuedBy` is
- * then absent, and `getProvider` never seeds from that secret.
+ * `saml2_bearer`: the client id, `uaaUrl`, the IdP's SSO URL, the ACS,
+ * `samlTokenUrl`, and `certUrl` when read; trust is the SAML trust and the
+ * client certificate. Fully stated with the client, the IdP, the token
+ * endpoint (`samlTokenUrl`, or `uaaUrl`) and — when read — `certUrl`.
+ */
+export declare function samlBearerBinding(means: IConnectionConfig, client: BoundClient | null, certificate: BoundCertificate | null): Binding;
+/**
+ * A `none` row: the resource, and the record — for `jwt` the client id,
+ * `uaaUrl` and `oidcIssuerUrl` as the means state them, for `saml` the ACS;
+ * no trust. A handed-over credential is compared by exact equality of the
+ * whole record; it is never seeded into a renewal, so it is not
+ * "fully stated".
+ */
+export declare function handedOverBinding(authType: 'jwt' | 'saml', means: IConnectionConfig, client: BoundClient | null): Binding;
+/**
+ * The token API with a consumer's provider: the `serviceUrl` it resolved,
+ * with the SAP client, and the record `provider/<row>` — for a factory the
+ * client id and `uaaUrl` of the client it was handed, for an instance (handed
+ * no client) none; no trust. Never fully stated: the broker cannot know what
+ * the factory composes, and an instance is handed no client.
+ */
+export declare function consumerBinding(row: string, serviceUrl: string, sapClient: string | undefined, client: BoundClient | null): Binding;
+/**
+ * A binding on the `clientAuthentication` strategy path: a resource that
+ * neither the means nor the stored session state matches
+ * (`Binding.unstatedResourceMatches`).
  */
-export declare function consumerBinding(serviceUrl: string, sapClient: string | undefined, client: IAuthorizationConfig | null): Binding;
+export declare function strategyBinding(binding: Binding): Binding;
 /**
- * A `none` row: the resource always; the issuer only when the means state one
- * — `oidcIssuerUrl` (with `uaaClientId` when stated) or the client (`uaaUrl`
- * and `uaaClientId`) for `jwt`, `samlAcsUrl` for `saml`.
+ * The stored `issuedFor`, canonicalised, equals the destination's — or, with
+ * `unstatedResourceMatches`, neither states one.
  */
-export declare function handedOverBinding(authType: 'jwt' | 'saml', means: IConnectionConfig, client: IAuthorizationConfig | null): Binding;
-/** The stored `issuedFor`, canonicalised, equals the destination's. */
 export declare function sameResource(stored: IConfig | null, binding: Binding): boolean;
-/** The stored `issuedBy`, canonicalised as the destination's kind, equals it. */
-export declare function sameIssuer(stored: IConfig | null, binding: Binding): boolean;
+/** The stored `issuedBy` is exactly this binding's record. */
+export declare function sameRecord(stored: IConfig | null, binding: Binding): boolean;
+/**
+ * Whether any stored secret could ever seed this binding's provider: the
+ * binding is fully stated and its resource can match — stated, or matching
+ * when neither side states one (`unstatedResourceMatches`). The condition
+ * `boundHere` needs beside the stored values.
+ */
+export declare function couldBeSeeded(binding: Binding): boolean;
 /**
- * An obtained secret is this destination's only when **both** stored values
- * equal the computed ones; either absent, on either side, is not a match.
+ * A stored secret may seed this binding's provider — or have its refresh
+ * token carried — only when the binding is fully stated, the resource
+ * matches, and the stored `issuedBy` is exactly the record. A session with no
+ * `issuedBy`, or a 4.x one, never matches.
  */
 export declare function boundHere(stored: IConfig | null, binding: Binding): boolean;
 //# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,iBAAiB,EAClB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AA6C9E;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,OAAO,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAEpB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,OAAO,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAEpB;AAED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE1D;AAED,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE1C,+FAA+F;AAC/F,MAAM,WAAW,OAAO;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,UAAU,EAAE,UAAU,CAAC;IACvB;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAUD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAClC,OAAO,CAUT;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAClC,OAAO,CAWT;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAOjE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAClC,OAAO,CAET;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,KAAK,GAAG,MAAM,EACxB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAClC,OAAO,CA4BT;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,GAAG,IAAI,EACtB,OAAO,EAAE,OAAO,GACf,OAAO,CAKT;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAI5E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAE3E"}
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"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"}