@bitspark/archon-cli 0.6.1

package/dist/src/cmd/login.d.ts

@@ -0,0 +1,148 @@
+/** Where the offers form writes its interactive lines and how it waits, injected so a test can
+ *  pin the code and the page mark on stderr, the pacing, and the ledger's wall-clock end —
+ *  without sleeping through the pacing or patching process streams. `run` hands the real ones. */
+export interface LoginIo {
+    writeErr: (text: string) => void;
+    sleep: (seconds: number) => Promise<void>;
+    /** Seconds since the Unix epoch. */
+    now: () => number;
+}
+/** What the service answers on GET <audience>/login/<id>.
+ *
+ *  NOTE the absent field: there is no `audience` here, by design (Finding 1). */
+export interface LoginRequest {
+    id: string;
+    /** hex */
+    nonce: string;
+    /** canonical key text, ed25519:<hex> */
+    browser: string;
+    /** ordered, verbatim, displayed to the person */
+    scope: string[];
+    /** seconds */
+    valid_for: number;
+    /** RFC 3339; when the REQUEST dies, not the delegation */
+    expires?: string;
+}
+/** What we POST to <audience>/login/<id>/answer. */
+export interface LoginAnswer {
+    principal: string;
+    possession: string;
+    authority: string;
+}
+/** WHICH custody will sign. Decided at flag-parse time — before the audience is derived —
+ *  so the statement can name it and a bad choice is refused before anything is fetched or
+ *  shown. */
+export interface LoginSource {
+    seedHex?: string;
+    keyFile?: string;
+    seedFile?: string;
+    /** A NAME in the store, never a principal (ADR 0007 §A). Set by --key, or by the store's
+     *  default pointer when no source flag was given. */
+    storeKey?: string;
+}
+/** Settles the source: exactly one flag, or none and the store's default. It never guesses
+ *  a seed file — the only fallback is the pointer the person set with `archon key default`.
+ *  A named store key is checked to EXIST here (a stat, opening nothing), so a typo is
+ *  refused before a pointless fetch; the password and the unlock still wait for consent. */
+export declare function decideLoginSource(src: LoginSource): void;
+/** Entry point. The order is the security order and is not an accident: derive the
+ *  audience, fetch, validate, SHOW, confirm, only then unlock and sign.
+ *
+ *  Everything decidable WITHOUT the network — which custody signs, whether the flags agree,
+ *  whether a named store key exists, whether the authority file is readable — is decided
+ *  first, so those refusals land before a request is made and before the person reads a
+ *  statement they could not have signed.
+ *
+ *  `write` is where the statement and the outcome go — stdout by default, and injectable so
+ *  a test can pin what a person would have seen WITHOUT patching process.stdout.write. Under
+ *  `node --test` the test file is a child that reports to the runner over its own stdout, so
+ *  a patch there swallows the report and silently drops tests from the run. */
+export declare function run(args: string[], write?: (text: string) => void, io?: LoginIo): Promise<void>;
+/** Refuse a malformed request BEFORE anything is displayed, so the person is never shown a
+ *  statement built from junk. Every refusal names the field. */
+export declare function validateLoginRequest(r: LoginRequest, wantId: string): void;
+/** EXACTLY what the person is asked to approve, and the text all three lanes must print
+ *  byte-identically. nowSeconds is a parameter so the wall-clock end is testable. */
+export declare function renderStatement(audience: string, r: LoginRequest, nowSeconds: number, keySource: string): string;
+/** The offers form's counterpart (docs/login.md §4.1 rule 4): the same fields as the
+ *  statement, printed AFTER answering rather than before signing, because in that form nobody
+ *  confirmed — the person typed the scope and the audience is the CLI's own. It names K as the
+ *  request delivered it, the source that signed, and the service's verdict (`undefined` for an
+ *  accepted answer, else the code). Never the code: the ledger goes to stdout, and stdout may
+ *  be a log. */
+export declare function renderLedger(audience: string, r: LoginRequest, nowSeconds: number, keySource: string, refused: string | undefined): string;
+/** Name the custody the signature will come from, for the last line of the statement
+ *  (seat:cca ruling, 2026-09-10).
+ *
+ *  It is the SOURCE and not the principal, on purpose: naming the principal would mean
+ *  unlocking the key before the person has agreed to sign — which, for a password-protected
+ *  store, means demanding a password in order to show someone what they are being asked to
+ *  approve. The source is known without touching the key at all.
+ *
+ *  A store key is named by its NAME, whether --key chose it or the default pointer did: the
+ *  statement says what will sign, and how the name was chosen is not part of what is being
+ *  approved. The pinned wording is cca's (2026-09-10 20:47Z). */
+export declare function describeKeySource(src: LoginSource): string;
+/** Render seconds the same way in every lane. Written out explicitly so Go and Rust
+ *  reproduce it exactly — a shared format nobody has to reverse-engineer. */
+export declare function formatDuration(seconds: number): string;
+/** Format a Unix timestamp as YYYY-MM-DDTHH:MM:SSZ, matching the other two lanes. */
+export declare function formatRfc3339Utc(unixSeconds: number): string;
+/** Read a y/N answer. Default is NO: anything that is not an explicit yes refuses,
+ *  including EOF, so a login cannot be completed by a closed stdin. */
+export declare function confirm(): Promise<boolean>;
+/** Accept the two hex seed-file shapes in use: 64 hex characters (a raw 32-byte seed) and
+ *  128 (seed followed by public key), the shape the first consumer's `key` files carry (answer 4). */
+export declare function seedFromHexFile(text: string): Uint8Array;
+/** GET the request. The CLI owns HTTP; the SDK never opens a socket (archon#16). */
+export declare function fetchLoginRequest(audience: string, id: string): Promise<LoginRequest>;
+/** Deliver the answer and report the service's verdict as an error, which is what the
+ *  confirmed form wants: a refusal ends the command. */
+export declare function postLoginAnswer(audience: string, id: string, answer: LoginAnswer): Promise<void>;
+/** The service's answer to an offer. `page`, when the service has one, is the address the
+ *  person opens, carrying the code in its fragment. No audience here either — in this form the
+ *  audience is the prover's own configuration — and a response carrying one is refused. */
+export interface OfferResponse {
+    code: string;
+    scope: string[];
+    valid_for: number;
+    expires_in: number;
+    interval: number;
+    page?: string;
+}
+/** The offers form. The order is §4.1's, rule by rule, and the same before-any-network
+ *  discipline as the confirmed form: everything decidable without the service — the custody,
+ *  the authority file, the scope, the validity, the audience — is decided first, so those
+ *  refusals land before an offer exists. */
+export declare function runOffer(args: string[], write: (text: string) => void, io: LoginIo): Promise<void>;
+/** §4.1 rule 1. The audience is --audience, or ARCHON_AUDIENCE as the configured default,
+ *  checked exactly the same way: it must be a fixed point of §2.1's grammar — the very check
+ *  the server applies to its own configuration — and the CLI refuses to start otherwise. The
+ *  `/login/00` is the shortest invocation URL the grammar admits, there only to make the
+ *  audience parseable as one; feeding the audience through the scheme's derivation asks the
+ *  one question that matters: is this the string the service binds? */
+export declare function configuredAudience(flag: string | undefined): string;
+/** The one line about the page address, printed and MARKED, never opened (§4.1 rule 1; ADR
+ *  0007 §C.7 (6)). "On the service's own origin" is a byte-exact comparison of scheme and host
+ *  with the audience's — a differently spelled origin fails closed, the right direction for an
+ *  address a person is about to click — and launching a browser is the person's action, never
+ *  this command's: spawning a platform opener by name is the PATH surface §C.5 refuses. */
+export declare function describePage(audience: string, page: string): string;
+/** §4.1 rule 2, done by the prover for itself: the request's scope must be what was offered,
+ *  entry for entry, in order, and its validity equal. The service refuses a mismatched begin
+ *  before storing anything — but a prover that relied on that would be trusting the service
+ *  about the one thing it is about to sign. */
+export declare function checkAgainstOffer(r: LoginRequest, scope: string[], validFor: number): void;
+/** Turn a non-success response into a diagnosis. RFC 8628's error vocabulary is used where
+ *  the service speaks it, since this protocol adopts that shape. */
+export declare function loginHttpError(status: number, body: string): string;
+/** The possession proof over this request, plus the person's principal as canonical key
+ *  text. The principal is derived here — a property of the seed, not of the scheme — so
+ *  only the proof itself waits on sdk/ts/login.
+ *
+ *  LOUD ON PURPOSE until then: a locally computed binding that merely looks right would
+ *  produce proofs that verify nowhere and take a day to explain. */
+export declare function proveLogin(seed: Uint8Array, audience: string, request: LoginRequest): {
+    proof: Uint8Array;
+    principal: string;
+};