@robota-sdk/agent-transport 3.0.0-beta.100

package/dist/node/node.d.cts

@@ -0,0 +1,317 @@
+import { IInteractiveSessionRecord } from "@robota-sdk/agent-interface-session";
+import { IAccessTokenVerifier, IAccessTokenVerifierConfig, ITransportAdmission, ITransportAdmissionConfig, TAccessTokenRefusal } from "@robota-sdk/agent-interface-transport";
+import { IFileFrameChannel, IFileOffer, IHandoffIntegrity } from "@robota-sdk/agent-interface-session-mobility";
+import { IEgressDeps } from "@robota-sdk/agent-core/node";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { PassThrough, Readable, Writable } from "node:stream";
+//#region src/node/admission.d.ts
+/**
+ * Mint a per-launch credential.
+ *
+ * Throws rather than returning a short or empty string if entropy is unavailable, so a transport
+ * built on it fails to construct instead of binding with a guessable credential.
+ */
+declare function mintTransportToken(): string;
+/**
+ * Resolve the admission decision for one transport.
+ *
+ * IDEMPOTENT: it accepts an already-resolved `ITransportAdmission` and returns it unchanged, so
+ * `resolve(resolve(x))` is `resolve(x)`. That is not a convenience — it is what lets a caller
+ * holding either shape just call this, instead of deciding which shape it holds first.
+ *
+ * The HTTP route used to make that decision with `'token' in options.admission`, and review showed
+ * it cannot work: BOTH interfaces declare a `token`, so a config is only distinguishable from a
+ * resolution by the VALUE. `{ token: '' }` — documented as "mint a fresh one" — was read as
+ * pre-resolved and installed the empty string as the required credential, which a peer sending an
+ * empty bearer would then match. Making this function idempotent deletes that discriminator
+ * instead of repairing it.
+ *
+ * @throws if `open` is set without a reason — an unexplained open transport is the state this
+ * module exists to remove, so it is refused at construction rather than recorded and shipped.
+ * @throws if a token and `open: true` are asked for together. The two are contradictory, and the
+ * silent precedence this used to give (token wins) is the safe DIRECTION but the wrong ANSWER: a
+ * caller that wrote both does not know what it is asking for, and one of the two things it believes
+ * is false. `WebRtcTransport` already refused the analogous `secret` + `open` pair in its own
+ * constructor; a seam whose whole claim is "one place to read and one place to change" cannot leave
+ * that protection to whichever transport happens to have implemented it.
+ */
+declare function resolveAdmission(config?: ITransportAdmissionConfig | ITransportAdmission): ITransportAdmission;
+/**
+ * Whether a presented credential matches the required one.
+ *
+ * Compared with `timingSafeEqual` over the raw bytes, so the answer takes the same time whatever the
+ * first differing character is. The length check before it is unavoidable — `timingSafeEqual` throws
+ * on unequal lengths — and it does leak one bit: whether the presented credential is the right
+ * LENGTH.
+ *
+ * For a minted token that costs nothing: the length is fixed at 64 hex characters and published in
+ * this file. A host that supplies its own token of some other length leaks that length instead, and
+ * review was right to point out that the earlier wording ("fixed and public") quietly assumed the
+ * minted case for every case. Length is not the secret in either — but the claim now says which
+ * situation it is describing.
+ *
+ * A missing credential is a mismatch, not a special case: a peer that sends nothing and a peer that
+ * sends the wrong thing are equally unadmitted, and giving them different answers would tell an
+ * attacker which half they got right.
+ */
+declare function credentialMatches(expected: string, presented: string | undefined): boolean;
+declare function bearerCredential(header: string | undefined | null): string | undefined;
+//#endregion
+//#region src/node/handoff-manifest.d.ts
+/**
+ * Serialize a record and describe what was serialized.
+ *
+ * The string is returned alongside the integrity data because the digest is only meaningful for
+ * these exact bytes. A caller that re-serialized the record before sending could produce a
+ * different key order and a digest mismatch on a payload that is perfectly correct — a corruption
+ * report caused by the corruption check.
+ */
+declare function sealHandoffRecord(record: IInteractiveSessionRecord): {
+  serialized: string;
+  integrity: IHandoffIntegrity;
+};
+/** Why a received payload was not accepted. */
+type TIntegrityFailure = 'truncated' | 'digest-mismatch';
+interface IIntegrityVerdict {
+  readonly intact: boolean;
+  readonly failure?: TIntegrityFailure;
+  /** What the manifest promised and what arrived, so a report can say more than "it failed". */
+  readonly expectedBytes?: number;
+  readonly actualBytes?: number;
+}
+/**
+ * Check a received payload against the manifest's integrity metadata.
+ *
+ * Nothing is parsed here. Parsing a payload to check it is well-formed would mean building the
+ * object graph before knowing whether the bytes are the ones that were sent, and a destination that
+ * has already parsed a corrupt payload has already spent the effort this check exists to avoid.
+ */
+declare function verifyHandoffPayload(serialized: string, integrity: IHandoffIntegrity): IIntegrityVerdict;
+//#endregion
+//#region src/node/access-token-verifier.d.ts
+/** What the verifier reaches outward through. Injected in tests; defaults to the real network. */
+interface IAccessTokenVerifierDeps {
+  readonly fetch?: IEgressDeps['fetch'];
+  readonly lookup?: IEgressDeps['lookup'];
+  /** Wall-clock milliseconds since the epoch, for `exp`/`nbf`. Defaults to `Date.now`. */
+  readonly now?: () => number;
+  /** Monotonic milliseconds, for cache age and refetch intervals. Defaults to `performance.now`. */
+  readonly monotonicNow?: () => number;
+}
+/**
+ * Build a verifier for one issuer and one resource.
+ *
+ * @throws when the configuration cannot describe a safe verifier: a non-`https` issuer, no
+ * algorithm or an unsupported one, no required scope, or no allowlisted subject or client. The
+ * last is the single-tenant rule: without it any holder of a token from the issuer is admitted.
+ */
+declare function createAccessTokenVerifier(config: IAccessTokenVerifierConfig, deps?: IAccessTokenVerifierDeps): IAccessTokenVerifier;
+//#endregion
+//#region src/node/bearer-resource-gate.d.ts
+/** A coarse class of a peer's address; the address itself is never reported. */
+type TRemoteAddressClass = 'loopback' | 'private' | 'public' | 'unknown';
+/** Where a refused request came from, and whether its address is over the failure budget. */
+interface IBearerFailure {
+  readonly remote: TRemoteAddressClass;
+  readonly throttled: boolean;
+  readonly retryAfterSeconds: number;
+}
+/** The public-facing identity of one resource server and its per-address failure budget. */
+interface IBearerResourceServer {
+  /** The parsed public URL; its path is the resource's base path. */
+  readonly url: URL;
+  /**
+   * Host and Origin must name the public URL. On a mismatch the 403 is written and false returned;
+   * nothing is counted, since no credential was judged.
+   */
+  checkNames(req: IncomingMessage, res: ServerResponse): boolean;
+  /** Count one failure against the request's peer. */
+  fail(req: IncomingMessage): IBearerFailure;
+  /** The request's peer class without counting anything. */
+  remote(req: IncomingMessage): TRemoteAddressClass;
+}
+/** The challenges and metadata of one protected resource (one audience). */
+interface IProtectedResource {
+  /** The RFC 9728 path clients fetch the metadata from. */
+  readonly wellKnownPath: string;
+  readonly metadata: string;
+  readonly challenges: {
+    readonly missing: string;
+    readonly invalid: string;
+    readonly scope: string;
+  };
+}
+/** Parse a resource server's public URL: plain `https`, no credentials, query or fragment. */
+declare function parsePublicHttpsUrl(publicUrl: string, label: string): URL;
+/**
+ * Build the public identity of a resource server. Throws when the public URL is not plain `https`,
+ * or a trusted proxy is not a literal address. `label` names the carrier in those messages.
+ */
+declare function createBearerResourceServer(options: {
+  readonly publicUrl: string;
+  /** Proxy addresses whose `X-Forwarded-For` is believed. Absent: the header is ignored. */
+  readonly trustedProxies?: readonly string[];
+  readonly label: string;
+  readonly now?: () => number;
+}): IBearerResourceServer;
+/**
+ * Describe one protected resource: where its RFC 9728 metadata lives and the challenges that point
+ * there. Throws for a non-`https` issuer, or no scope or a scope a challenge cannot quote.
+ */
+declare function describeProtectedResource(options: {
+  /** The resource identifier (`aud`), an `https` URL. */
+  readonly resource: string;
+  readonly issuer: string;
+  readonly scopes: readonly string[];
+  readonly label: string;
+}): IProtectedResource;
+/** Answer a metadata request: GET only, the JSON document, nothing else. */
+declare function serveProtectedResourceMetadata(req: IncomingMessage, res: ServerResponse, resource: IProtectedResource): void;
+/**
+ * Answer a refused bearer token after its failure was counted: 429 once the peer is over budget,
+ * 403 `insufficient_scope` for a missing scope, otherwise 401 with the missing-token or
+ * `invalid_token` challenge. Always an empty body.
+ */
+declare function refuseBearerToken(res: ServerResponse, resource: IProtectedResource, refusal: 'missing-token' | 'missing-scope' | 'invalid-token', failure: IBearerFailure): void;
+/** Why a request was refused: a verifier refusal, or no bearer token at all. */
+type TBearerRefusal = TAccessTokenRefusal | 'missing-token';
+/** One refused request as an audit sink sees it. Carries no token text and no claim value. */
+interface IBearerRefusalRecord {
+  readonly refusal: TBearerRefusal;
+  readonly remote: TRemoteAddressClass;
+  /** True when the refusal was answered 429 because the address exceeded its failure budget. */
+  readonly throttled: boolean;
+}
+/**
+ * Answer one refused request and report it. When the issuer's keys are unavailable the issuer, not
+ * the peer, failed: 503, not counted against the peer, and not a token verdict. Every other refusal
+ * is counted and answered with the matching challenge.
+ */
+declare function refuseAccessToken(req: IncomingMessage, res: ServerResponse, server: IBearerResourceServer, resource: IProtectedResource, refusal: TBearerRefusal, audit?: (record: IBearerRefusalRecord) => void): void;
+//#endregion
+//#region src/node/file-transfer.d.ts
+/** Why a transfer did not end with the file kept. */
+type TFileTransferRefusal =
+/** The receiving operator said no, could not be asked, or the connection does not carry files. */
+'declined' |
+/** The file is over the size limit. */
+'too-large' |
+/** The name is empty, or would leave the receiving directory. */
+'bad-name' |
+/** A file of that name was already received; nothing is overwritten. */
+'exists' |
+/** The receiving directory is not one this user owns outright, e.g. a symbolic link. */
+'unsafe-path' |
+/** The content did not match the offered size or hash. The partial file is discarded. */
+'integrity' |
+/** A frame broke the protocol. */
+'protocol' |
+/** The channel ended first. */
+'closed' |
+/** The other side went quiet. */
+'timeout' |
+/** The receiver could not store the file. */
+'unavailable';
+/**
+ * The default size limit. A transfer does not resume, so a dropped connection costs the whole file
+ * again; a received file also sits on the receiver's disk until its operator removes it. The limit
+ * keeps both costs small while covering what is sent between one's own sessions: sources, logs,
+ * screenshots, a small archive.
+ */
+declare const DEFAULT_MAX_FILE_BYTES: number;
+/**
+ * Bytes of content per chunk. Small enough that a frame, base64 and envelope included, stays well
+ * inside the message size every channel it runs on carries.
+ */
+declare const FILE_CHUNK_BYTES: number;
+/** Chunks the sender may have unconfirmed. */
+declare const FILE_CREDIT_WINDOW = 16;
+/** Where content comes from. `read` yields the content once, in order, in pieces of any size. */
+interface IFileSource {
+  readonly size: number;
+  read(): AsyncIterable<Uint8Array>;
+}
+/** Where received content goes until it is verified; nothing is kept unless `commit` runs. */
+interface IFileSink {
+  write(chunk: Uint8Array): Promise<void>;
+  /** Keep the verified file. Resolves with where it is. */
+  commit(): Promise<string>;
+  /** Drop what was written. */
+  discard(): Promise<void>;
+}
+/** The receiver's decision on an offer: somewhere to put it, or why not. */
+type TFileAdmission = {
+  readonly sink: IFileSink;
+} | {
+  readonly refused: TFileTransferRefusal;
+  readonly detail?: string;
+};
+type TFileSendOutcome = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly reason: TFileTransferRefusal;
+  readonly detail?: string;
+};
+type TFileReceiveOutcome = {
+  readonly ok: true;
+  readonly offer: IFileOffer;
+  readonly location: string;
+} | {
+  readonly ok: false;
+  readonly reason: TFileTransferRefusal;
+  readonly detail?: string;
+  readonly offer?: IFileOffer;
+};
+interface ISendFileOptions {
+  readonly channel: IFileFrameChannel;
+  readonly offer: IFileOffer;
+  readonly source: IFileSource;
+  readonly chunkBytes?: number;
+  readonly window?: number;
+  readonly idleMs?: number;
+  /** How long the receiving operator may take to answer. */
+  readonly decisionMs?: number;
+}
+/**
+ * Offer a file and, once accepted, send it. Resolves when the receiver confirms it kept the file, or
+ * with why it did not. Closes the channel either way.
+ */
+declare function sendFileOverChannel(options: ISendFileOptions): Promise<TFileSendOutcome>;
+interface IReceiveFileOptions {
+  readonly channel: IFileFrameChannel;
+  /** Offers above this are refused without asking anyone. */
+  readonly maxBytes?: number;
+  /**
+   * Decide on a well-formed offer within the size limit: ask whoever must approve it, and open
+   * somewhere to put it. `signal` aborts when the sender goes away.
+   */
+  readonly admit: (offer: IFileOffer, signal: AbortSignal) => Promise<TFileAdmission>;
+  readonly window?: number;
+  readonly idleMs?: number;
+}
+/**
+ * Receive one file: the channel's first frame is the offer. Resolves with where the verified file was
+ * kept, or with why nothing was. Closes the channel either way.
+ */
+declare function receiveFileOverChannel(options: IReceiveFileOptions): Promise<TFileReceiveOutcome>;
+//#endregion
+//#region src/node/stdio-carrier.d.ts
+interface IStdioCarrierHandlers {
+  /** The peer ended its side: `end` or `close` on the input. May fire more than once. */
+  readonly onInputClose: () => void;
+  /** The output closed. */
+  readonly onOutputClose: () => void;
+  /** The output failed to accept a write. */
+  readonly onOutputError: (error: Error) => void;
+}
+interface IStdioCarrier {
+  /** Hand this to the protocol SDK in place of the input; destroying it never destroys the input. */
+  readonly bridge: PassThrough;
+  /** Remove the listeners, unpipe and destroy the bridge. Safe to call again; the streams stay open. */
+  release(): void;
+}
+declare function attachStdioCarrier(input: Readable, output: Writable, handlers: IStdioCarrierHandlers): IStdioCarrier;
+//#endregion
+export { DEFAULT_MAX_FILE_BYTES, FILE_CHUNK_BYTES, FILE_CREDIT_WINDOW, type IAccessTokenVerifierDeps, type IBearerFailure, type IBearerRefusalRecord, type IBearerResourceServer, type IFileSink, type IFileSource, type IIntegrityVerdict, type IProtectedResource, type IReceiveFileOptions, type ISendFileOptions, type IStdioCarrier, type IStdioCarrierHandlers, type TBearerRefusal, type TFileAdmission, type TFileReceiveOutcome, type TFileSendOutcome, type TFileTransferRefusal, type TIntegrityFailure, type TRemoteAddressClass, attachStdioCarrier, bearerCredential, createAccessTokenVerifier, createBearerResourceServer, credentialMatches, describeProtectedResource, mintTransportToken, parsePublicHttpsUrl, receiveFileOverChannel, refuseAccessToken, refuseBearerToken, resolveAdmission, sealHandoffRecord, sendFileOverChannel, serveProtectedResourceMetadata, verifyHandoffPayload };
+//# sourceMappingURL=node.d.cts.map

package/dist/node/node.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.cts","names":[],"sources":["../../src/node/admission.ts","../../src/node/handoff-manifest.ts","../../src/node/access-token-verifier.ts","../../src/node/bearer-resource-gate.ts","../../src/node/file-transfer.ts","../../src/node/stdio-carrier.ts"],"mappings":";;;;;;;;;;;;;iBA4BgB;;;;;;;;;;;;;;;;;;;;;;;;iBA+BA,iBACd,SAAQ,4BAA4B,sBACnC;;;;;;;;;;;;;;;;;;;iBAoDa,kBAAkB,kBAAkB;iBA8BpC,iBAAiB;;;;;;;;;;;iBCpHjB,kBAAkB,QAAQ;EACxC;EACA,WAAW;;;KAcD;UAEK;WACN;WACA,UAAU;;WAEV;WACA;;;;;;;;;iBAUK,qBACd,oBACA,WAAW,oBACV;;;;UCCc;WACN,QAAQ;WACR,SAAS;;WAET;;WAEA;;;;;;;;;iBAwBK,0BACd,QAAQ,4BACR,OAAM,2BACL;;;;KC9DS;;UAGK;WACN,QAAQ;WACR;WACA;;;UAIM;;WAEN,KAAK;;;;;EAKd,WAAW,KAAK,iBAAiB,KAAK;;EAEtC,KAAK,KAAK,kBAAkB;;EAE5B,OAAO,KAAK,kBAAkB;;;UAIf;;WAEN;WACA;WACA;aACE;aACA;aACA;;;;iBAkCG,oBAAoB,mBAAmB,gBAAgB;;;;;iBAoDvD,2BAA2B;WAChC;;WAEA;WACA;WACA;IACP;;;;;iBA0DY,0BAA0B;;WAE/B;WACA;WACA;WACA;IACP;;iBAoCY,+BACd,KAAK,iBACL,KAAK,gBACL,UAAU;;;;;;iBAcI,kBACd,KAAK,gBACL,UAAU,oBACV,8DACA,SAAS;;KAcC,iBAAiB;;UAGZ;WACN,SAAS;WACT,QAAQ;;WAER;;;;;;;iBAQK,kBACd,KAAK,iBACL,KAAK,gBACL,QAAQ,uBACR,UAAU,oBACV,SAAS,gBACT,SAAS,QAAQ;;;;KC7RP;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4BC;;;;;cAMA;;cAEA;;UAcI;WACN;EACT,QAAQ,cAAc;;;UAIP;EACf,MAAM,OAAO,aAAa;;EAE1B,UAAU;;EAEV,WAAW;;;KAID;WACG,MAAM;;WACN,SAAS;WAA+B;;KAE3C;WACG;;WACA;WAAoB,QAAQ;WAA+B;;KAE9D;WACG;WAAmB,OAAO;WAAqB;;WAE/C;WACA,QAAQ;WACR;WACA,QAAQ;;UA4NN;WACN,SAAS;WACT,OAAO;WACP,QAAQ;WACR;WACA;WACA;;WAEA;;;;;;iBAOW,oBAAoB,SAAS,mBAAmB,QAAQ;UA2D7D;WACN,SAAS;;WAET;;;;;WAKA,QAAQ,OAAO,YAAY,QAAQ,gBAAgB,QAAQ;WAC3D;WACA;;;;;;iBAOW,uBACpB,SAAS,sBACR,QAAQ;;;UCrZM;;WAEN;;WAEA;;WAEA,gBAAgB,OAAO;;UAGjB;;WAEN,QAAQ;;EAEjB;;iBAGc,mBACd,OAAO,UACP,QAAQ,UACR,UAAU,wBACT"}

package/dist/node/node.d.ts

@@ -0,0 +1,317 @@
+import { IInteractiveSessionRecord } from "@robota-sdk/agent-interface-session";
+import { IEgressDeps } from "@robota-sdk/agent-core/node";
+import { PassThrough, Readable, Writable } from "node:stream";
+import { IAccessTokenVerifier, IAccessTokenVerifierConfig, ITransportAdmission, ITransportAdmissionConfig, TAccessTokenRefusal } from "@robota-sdk/agent-interface-transport";
+import { IFileFrameChannel, IFileOffer, IHandoffIntegrity } from "@robota-sdk/agent-interface-session-mobility";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/node/admission.d.ts
+/**
+ * Mint a per-launch credential.
+ *
+ * Throws rather than returning a short or empty string if entropy is unavailable, so a transport
+ * built on it fails to construct instead of binding with a guessable credential.
+ */
+declare function mintTransportToken(): string;
+/**
+ * Resolve the admission decision for one transport.
+ *
+ * IDEMPOTENT: it accepts an already-resolved `ITransportAdmission` and returns it unchanged, so
+ * `resolve(resolve(x))` is `resolve(x)`. That is not a convenience — it is what lets a caller
+ * holding either shape just call this, instead of deciding which shape it holds first.
+ *
+ * The HTTP route used to make that decision with `'token' in options.admission`, and review showed
+ * it cannot work: BOTH interfaces declare a `token`, so a config is only distinguishable from a
+ * resolution by the VALUE. `{ token: '' }` — documented as "mint a fresh one" — was read as
+ * pre-resolved and installed the empty string as the required credential, which a peer sending an
+ * empty bearer would then match. Making this function idempotent deletes that discriminator
+ * instead of repairing it.
+ *
+ * @throws if `open` is set without a reason — an unexplained open transport is the state this
+ * module exists to remove, so it is refused at construction rather than recorded and shipped.
+ * @throws if a token and `open: true` are asked for together. The two are contradictory, and the
+ * silent precedence this used to give (token wins) is the safe DIRECTION but the wrong ANSWER: a
+ * caller that wrote both does not know what it is asking for, and one of the two things it believes
+ * is false. `WebRtcTransport` already refused the analogous `secret` + `open` pair in its own
+ * constructor; a seam whose whole claim is "one place to read and one place to change" cannot leave
+ * that protection to whichever transport happens to have implemented it.
+ */
+declare function resolveAdmission(config?: ITransportAdmissionConfig | ITransportAdmission): ITransportAdmission;
+/**
+ * Whether a presented credential matches the required one.
+ *
+ * Compared with `timingSafeEqual` over the raw bytes, so the answer takes the same time whatever the
+ * first differing character is. The length check before it is unavoidable — `timingSafeEqual` throws
+ * on unequal lengths — and it does leak one bit: whether the presented credential is the right
+ * LENGTH.
+ *
+ * For a minted token that costs nothing: the length is fixed at 64 hex characters and published in
+ * this file. A host that supplies its own token of some other length leaks that length instead, and
+ * review was right to point out that the earlier wording ("fixed and public") quietly assumed the
+ * minted case for every case. Length is not the secret in either — but the claim now says which
+ * situation it is describing.
+ *
+ * A missing credential is a mismatch, not a special case: a peer that sends nothing and a peer that
+ * sends the wrong thing are equally unadmitted, and giving them different answers would tell an
+ * attacker which half they got right.
+ */
+declare function credentialMatches(expected: string, presented: string | undefined): boolean;
+declare function bearerCredential(header: string | undefined | null): string | undefined;
+//#endregion
+//#region src/node/handoff-manifest.d.ts
+/**
+ * Serialize a record and describe what was serialized.
+ *
+ * The string is returned alongside the integrity data because the digest is only meaningful for
+ * these exact bytes. A caller that re-serialized the record before sending could produce a
+ * different key order and a digest mismatch on a payload that is perfectly correct — a corruption
+ * report caused by the corruption check.
+ */
+declare function sealHandoffRecord(record: IInteractiveSessionRecord): {
+  serialized: string;
+  integrity: IHandoffIntegrity;
+};
+/** Why a received payload was not accepted. */
+type TIntegrityFailure = 'truncated' | 'digest-mismatch';
+interface IIntegrityVerdict {
+  readonly intact: boolean;
+  readonly failure?: TIntegrityFailure;
+  /** What the manifest promised and what arrived, so a report can say more than "it failed". */
+  readonly expectedBytes?: number;
+  readonly actualBytes?: number;
+}
+/**
+ * Check a received payload against the manifest's integrity metadata.
+ *
+ * Nothing is parsed here. Parsing a payload to check it is well-formed would mean building the
+ * object graph before knowing whether the bytes are the ones that were sent, and a destination that
+ * has already parsed a corrupt payload has already spent the effort this check exists to avoid.
+ */
+declare function verifyHandoffPayload(serialized: string, integrity: IHandoffIntegrity): IIntegrityVerdict;
+//#endregion
+//#region src/node/access-token-verifier.d.ts
+/** What the verifier reaches outward through. Injected in tests; defaults to the real network. */
+interface IAccessTokenVerifierDeps {
+  readonly fetch?: IEgressDeps['fetch'];
+  readonly lookup?: IEgressDeps['lookup'];
+  /** Wall-clock milliseconds since the epoch, for `exp`/`nbf`. Defaults to `Date.now`. */
+  readonly now?: () => number;
+  /** Monotonic milliseconds, for cache age and refetch intervals. Defaults to `performance.now`. */
+  readonly monotonicNow?: () => number;
+}
+/**
+ * Build a verifier for one issuer and one resource.
+ *
+ * @throws when the configuration cannot describe a safe verifier: a non-`https` issuer, no
+ * algorithm or an unsupported one, no required scope, or no allowlisted subject or client. The
+ * last is the single-tenant rule: without it any holder of a token from the issuer is admitted.
+ */
+declare function createAccessTokenVerifier(config: IAccessTokenVerifierConfig, deps?: IAccessTokenVerifierDeps): IAccessTokenVerifier;
+//#endregion
+//#region src/node/bearer-resource-gate.d.ts
+/** A coarse class of a peer's address; the address itself is never reported. */
+type TRemoteAddressClass = 'loopback' | 'private' | 'public' | 'unknown';
+/** Where a refused request came from, and whether its address is over the failure budget. */
+interface IBearerFailure {
+  readonly remote: TRemoteAddressClass;
+  readonly throttled: boolean;
+  readonly retryAfterSeconds: number;
+}
+/** The public-facing identity of one resource server and its per-address failure budget. */
+interface IBearerResourceServer {
+  /** The parsed public URL; its path is the resource's base path. */
+  readonly url: URL;
+  /**
+   * Host and Origin must name the public URL. On a mismatch the 403 is written and false returned;
+   * nothing is counted, since no credential was judged.
+   */
+  checkNames(req: IncomingMessage, res: ServerResponse): boolean;
+  /** Count one failure against the request's peer. */
+  fail(req: IncomingMessage): IBearerFailure;
+  /** The request's peer class without counting anything. */
+  remote(req: IncomingMessage): TRemoteAddressClass;
+}
+/** The challenges and metadata of one protected resource (one audience). */
+interface IProtectedResource {
+  /** The RFC 9728 path clients fetch the metadata from. */
+  readonly wellKnownPath: string;
+  readonly metadata: string;
+  readonly challenges: {
+    readonly missing: string;
+    readonly invalid: string;
+    readonly scope: string;
+  };
+}
+/** Parse a resource server's public URL: plain `https`, no credentials, query or fragment. */
+declare function parsePublicHttpsUrl(publicUrl: string, label: string): URL;
+/**
+ * Build the public identity of a resource server. Throws when the public URL is not plain `https`,
+ * or a trusted proxy is not a literal address. `label` names the carrier in those messages.
+ */
+declare function createBearerResourceServer(options: {
+  readonly publicUrl: string;
+  /** Proxy addresses whose `X-Forwarded-For` is believed. Absent: the header is ignored. */
+  readonly trustedProxies?: readonly string[];
+  readonly label: string;
+  readonly now?: () => number;
+}): IBearerResourceServer;
+/**
+ * Describe one protected resource: where its RFC 9728 metadata lives and the challenges that point
+ * there. Throws for a non-`https` issuer, or no scope or a scope a challenge cannot quote.
+ */
+declare function describeProtectedResource(options: {
+  /** The resource identifier (`aud`), an `https` URL. */
+  readonly resource: string;
+  readonly issuer: string;
+  readonly scopes: readonly string[];
+  readonly label: string;
+}): IProtectedResource;
+/** Answer a metadata request: GET only, the JSON document, nothing else. */
+declare function serveProtectedResourceMetadata(req: IncomingMessage, res: ServerResponse, resource: IProtectedResource): void;
+/**
+ * Answer a refused bearer token after its failure was counted: 429 once the peer is over budget,
+ * 403 `insufficient_scope` for a missing scope, otherwise 401 with the missing-token or
+ * `invalid_token` challenge. Always an empty body.
+ */
+declare function refuseBearerToken(res: ServerResponse, resource: IProtectedResource, refusal: 'missing-token' | 'missing-scope' | 'invalid-token', failure: IBearerFailure): void;
+/** Why a request was refused: a verifier refusal, or no bearer token at all. */
+type TBearerRefusal = TAccessTokenRefusal | 'missing-token';
+/** One refused request as an audit sink sees it. Carries no token text and no claim value. */
+interface IBearerRefusalRecord {
+  readonly refusal: TBearerRefusal;
+  readonly remote: TRemoteAddressClass;
+  /** True when the refusal was answered 429 because the address exceeded its failure budget. */
+  readonly throttled: boolean;
+}
+/**
+ * Answer one refused request and report it. When the issuer's keys are unavailable the issuer, not
+ * the peer, failed: 503, not counted against the peer, and not a token verdict. Every other refusal
+ * is counted and answered with the matching challenge.
+ */
+declare function refuseAccessToken(req: IncomingMessage, res: ServerResponse, server: IBearerResourceServer, resource: IProtectedResource, refusal: TBearerRefusal, audit?: (record: IBearerRefusalRecord) => void): void;
+//#endregion
+//#region src/node/file-transfer.d.ts
+/** Why a transfer did not end with the file kept. */
+type TFileTransferRefusal =
+/** The receiving operator said no, could not be asked, or the connection does not carry files. */
+'declined' |
+/** The file is over the size limit. */
+'too-large' |
+/** The name is empty, or would leave the receiving directory. */
+'bad-name' |
+/** A file of that name was already received; nothing is overwritten. */
+'exists' |
+/** The receiving directory is not one this user owns outright, e.g. a symbolic link. */
+'unsafe-path' |
+/** The content did not match the offered size or hash. The partial file is discarded. */
+'integrity' |
+/** A frame broke the protocol. */
+'protocol' |
+/** The channel ended first. */
+'closed' |
+/** The other side went quiet. */
+'timeout' |
+/** The receiver could not store the file. */
+'unavailable';
+/**
+ * The default size limit. A transfer does not resume, so a dropped connection costs the whole file
+ * again; a received file also sits on the receiver's disk until its operator removes it. The limit
+ * keeps both costs small while covering what is sent between one's own sessions: sources, logs,
+ * screenshots, a small archive.
+ */
+declare const DEFAULT_MAX_FILE_BYTES: number;
+/**
+ * Bytes of content per chunk. Small enough that a frame, base64 and envelope included, stays well
+ * inside the message size every channel it runs on carries.
+ */
+declare const FILE_CHUNK_BYTES: number;
+/** Chunks the sender may have unconfirmed. */
+declare const FILE_CREDIT_WINDOW = 16;
+/** Where content comes from. `read` yields the content once, in order, in pieces of any size. */
+interface IFileSource {
+  readonly size: number;
+  read(): AsyncIterable<Uint8Array>;
+}
+/** Where received content goes until it is verified; nothing is kept unless `commit` runs. */
+interface IFileSink {
+  write(chunk: Uint8Array): Promise<void>;
+  /** Keep the verified file. Resolves with where it is. */
+  commit(): Promise<string>;
+  /** Drop what was written. */
+  discard(): Promise<void>;
+}
+/** The receiver's decision on an offer: somewhere to put it, or why not. */
+type TFileAdmission = {
+  readonly sink: IFileSink;
+} | {
+  readonly refused: TFileTransferRefusal;
+  readonly detail?: string;
+};
+type TFileSendOutcome = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly reason: TFileTransferRefusal;
+  readonly detail?: string;
+};
+type TFileReceiveOutcome = {
+  readonly ok: true;
+  readonly offer: IFileOffer;
+  readonly location: string;
+} | {
+  readonly ok: false;
+  readonly reason: TFileTransferRefusal;
+  readonly detail?: string;
+  readonly offer?: IFileOffer;
+};
+interface ISendFileOptions {
+  readonly channel: IFileFrameChannel;
+  readonly offer: IFileOffer;
+  readonly source: IFileSource;
+  readonly chunkBytes?: number;
+  readonly window?: number;
+  readonly idleMs?: number;
+  /** How long the receiving operator may take to answer. */
+  readonly decisionMs?: number;
+}
+/**
+ * Offer a file and, once accepted, send it. Resolves when the receiver confirms it kept the file, or
+ * with why it did not. Closes the channel either way.
+ */
+declare function sendFileOverChannel(options: ISendFileOptions): Promise<TFileSendOutcome>;
+interface IReceiveFileOptions {
+  readonly channel: IFileFrameChannel;
+  /** Offers above this are refused without asking anyone. */
+  readonly maxBytes?: number;
+  /**
+   * Decide on a well-formed offer within the size limit: ask whoever must approve it, and open
+   * somewhere to put it. `signal` aborts when the sender goes away.
+   */
+  readonly admit: (offer: IFileOffer, signal: AbortSignal) => Promise<TFileAdmission>;
+  readonly window?: number;
+  readonly idleMs?: number;
+}
+/**
+ * Receive one file: the channel's first frame is the offer. Resolves with where the verified file was
+ * kept, or with why nothing was. Closes the channel either way.
+ */
+declare function receiveFileOverChannel(options: IReceiveFileOptions): Promise<TFileReceiveOutcome>;
+//#endregion
+//#region src/node/stdio-carrier.d.ts
+interface IStdioCarrierHandlers {
+  /** The peer ended its side: `end` or `close` on the input. May fire more than once. */
+  readonly onInputClose: () => void;
+  /** The output closed. */
+  readonly onOutputClose: () => void;
+  /** The output failed to accept a write. */
+  readonly onOutputError: (error: Error) => void;
+}
+interface IStdioCarrier {
+  /** Hand this to the protocol SDK in place of the input; destroying it never destroys the input. */
+  readonly bridge: PassThrough;
+  /** Remove the listeners, unpipe and destroy the bridge. Safe to call again; the streams stay open. */
+  release(): void;
+}
+declare function attachStdioCarrier(input: Readable, output: Writable, handlers: IStdioCarrierHandlers): IStdioCarrier;
+//#endregion
+export { DEFAULT_MAX_FILE_BYTES, FILE_CHUNK_BYTES, FILE_CREDIT_WINDOW, type IAccessTokenVerifierDeps, type IBearerFailure, type IBearerRefusalRecord, type IBearerResourceServer, type IFileSink, type IFileSource, type IIntegrityVerdict, type IProtectedResource, type IReceiveFileOptions, type ISendFileOptions, type IStdioCarrier, type IStdioCarrierHandlers, type TBearerRefusal, type TFileAdmission, type TFileReceiveOutcome, type TFileSendOutcome, type TFileTransferRefusal, type TIntegrityFailure, type TRemoteAddressClass, attachStdioCarrier, bearerCredential, createAccessTokenVerifier, createBearerResourceServer, credentialMatches, describeProtectedResource, mintTransportToken, parsePublicHttpsUrl, receiveFileOverChannel, refuseAccessToken, refuseBearerToken, resolveAdmission, sealHandoffRecord, sendFileOverChannel, serveProtectedResourceMetadata, verifyHandoffPayload };
+//# sourceMappingURL=node.d.ts.map

package/dist/node/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","names":[],"sources":["../../src/node/admission.ts","../../src/node/handoff-manifest.ts","../../src/node/access-token-verifier.ts","../../src/node/bearer-resource-gate.ts","../../src/node/file-transfer.ts","../../src/node/stdio-carrier.ts"],"mappings":";;;;;;;;;;;;;iBA4BgB;;;;;;;;;;;;;;;;;;;;;;;;iBA+BA,iBACd,SAAQ,4BAA4B,sBACnC;;;;;;;;;;;;;;;;;;;iBAoDa,kBAAkB,kBAAkB;iBA8BpC,iBAAiB;;;;;;;;;;;iBCpHjB,kBAAkB,QAAQ;EACxC;EACA,WAAW;;;KAcD;UAEK;WACN;WACA,UAAU;;WAEV;WACA;;;;;;;;;iBAUK,qBACd,oBACA,WAAW,oBACV;;;;UCCc;WACN,QAAQ;WACR,SAAS;;WAET;;WAEA;;;;;;;;;iBAwBK,0BACd,QAAQ,4BACR,OAAM,2BACL;;;;KC9DS;;UAGK;WACN,QAAQ;WACR;WACA;;;UAIM;;WAEN,KAAK;;;;;EAKd,WAAW,KAAK,iBAAiB,KAAK;;EAEtC,KAAK,KAAK,kBAAkB;;EAE5B,OAAO,KAAK,kBAAkB;;;UAIf;;WAEN;WACA;WACA;aACE;aACA;aACA;;;;iBAkCG,oBAAoB,mBAAmB,gBAAgB;;;;;iBAoDvD,2BAA2B;WAChC;;WAEA;WACA;WACA;IACP;;;;;iBA0DY,0BAA0B;;WAE/B;WACA;WACA;WACA;IACP;;iBAoCY,+BACd,KAAK,iBACL,KAAK,gBACL,UAAU;;;;;;iBAcI,kBACd,KAAK,gBACL,UAAU,oBACV,8DACA,SAAS;;KAcC,iBAAiB;;UAGZ;WACN,SAAS;WACT,QAAQ;;WAER;;;;;;;iBAQK,kBACd,KAAK,iBACL,KAAK,gBACL,QAAQ,uBACR,UAAU,oBACV,SAAS,gBACT,SAAS,QAAQ;;;;KC7RP;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4BC;;;;;cAMA;;cAEA;;UAcI;WACN;EACT,QAAQ,cAAc;;;UAIP;EACf,MAAM,OAAO,aAAa;;EAE1B,UAAU;;EAEV,WAAW;;;KAID;WACG,MAAM;;WACN,SAAS;WAA+B;;KAE3C;WACG;;WACA;WAAoB,QAAQ;WAA+B;;KAE9D;WACG;WAAmB,OAAO;WAAqB;;WAE/C;WACA,QAAQ;WACR;WACA,QAAQ;;UA4NN;WACN,SAAS;WACT,OAAO;WACP,QAAQ;WACR;WACA;WACA;;WAEA;;;;;;iBAOW,oBAAoB,SAAS,mBAAmB,QAAQ;UA2D7D;WACN,SAAS;;WAET;;;;;WAKA,QAAQ,OAAO,YAAY,QAAQ,gBAAgB,QAAQ;WAC3D;WACA;;;;;;iBAOW,uBACpB,SAAS,sBACR,QAAQ;;;UCrZM;;WAEN;;WAEA;;WAEA,gBAAgB,OAAO;;UAGjB;;WAEN,QAAQ;;EAEjB;;iBAGc,mBACd,OAAO,UACP,QAAQ,UACR,UAAU,wBACT"}