@magield/node 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026 MagicShield. All rights reserved.
+
+MAGIC SHIELD SDK LICENCE
+
+This package is published to a public registry so that licensed customers can
+install it with ordinary tooling. Being able to download it does not grant any
+right to use it.
+
+You may install, use and redistribute this package, unmodified and only as part
+of your own application, solely to integrate that application with a Magic
+Shield deployment that you are licensed to use under a written agreement with
+MagicShield ("your Agreement"), and only for the term of your Agreement.
+
+Except as your Agreement expressly allows, you may not:
+
+  - use this package for any other purpose, including to build, benchmark or
+    assist a competing product;
+  - modify it, or reverse engineer, decompile, deobfuscate or disassemble it,
+    except to the extent this restriction is unenforceable under applicable law;
+  - remove or alter this notice or any copyright or attribution in it.
+
+THE PACKAGE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXCEPT AS YOUR
+AGREEMENT PROVIDES. IN NO EVENT SHALL MAGICSHIELD BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY ARISING FROM THE PACKAGE OR ITS USE, EXCEPT AS YOUR
+AGREEMENT PROVIDES.
+
+Your Agreement governs if it conflicts with this notice.

package/dist/breaker.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A circuit breaker over a rolling window.
+ *
+ * `docs/api.md` §5 promises one, and the reason is latency rather than load.
+ * When the gateway is unreachable, every call still pays its full deadline
+ * before failing open — forty milliseconds added to every sign-in, for as long
+ * as the outage lasts. The breaker is what turns that into forty milliseconds
+ * once and then nothing.
+ *
+ * Counts rather than a rate: a window with three calls in it has no meaningful
+ * error rate, and tripping on one failure out of two would take a deployment
+ * offline over a single timeout. `MIN_CALLS` is the floor below which the
+ * breaker declines to have an opinion.
+ *
+ * Half-open is a single probe. Letting the whole load through the moment the
+ * reset elapses is how a recovering service gets knocked over again by the
+ * traffic that was waiting for it.
+ */
+export interface BreakerOptions {
+    /** Share of calls that must fail before the circuit opens. */
+    readonly errorThreshold?: number;
+    readonly windowMs?: number;
+    readonly resetMs?: number;
+}
+type State = 'closed' | 'open' | 'half_open';
+export declare class Breaker {
+    #private;
+    constructor(options?: BreakerOptions, now?: () => number);
+    get state(): State;
+    /**
+     * Whether to attempt the call.
+     *
+     * Moves the breaker to half-open as a side effect once the reset has elapsed,
+     * so exactly one caller gets through to find out whether the service is back.
+     */
+    allows(): boolean;
+    succeeded(): void;
+    failed(): void;
+}
+export {};
+//# sourceMappingURL=breaker.d.ts.map

package/dist/breaker.js

@@ -0,0 +1,91 @@
+/**
+ * A circuit breaker over a rolling window.
+ *
+ * `docs/api.md` §5 promises one, and the reason is latency rather than load.
+ * When the gateway is unreachable, every call still pays its full deadline
+ * before failing open — forty milliseconds added to every sign-in, for as long
+ * as the outage lasts. The breaker is what turns that into forty milliseconds
+ * once and then nothing.
+ *
+ * Counts rather than a rate: a window with three calls in it has no meaningful
+ * error rate, and tripping on one failure out of two would take a deployment
+ * offline over a single timeout. `MIN_CALLS` is the floor below which the
+ * breaker declines to have an opinion.
+ *
+ * Half-open is a single probe. Letting the whole load through the moment the
+ * reset elapses is how a recovering service gets knocked over again by the
+ * traffic that was waiting for it.
+ */
+const DEFAULTS = { errorThreshold: 0.5, windowMs: 10_000, resetMs: 30_000 };
+/** Below this, a failure rate is noise. */
+const MIN_CALLS = 5;
+export class Breaker {
+    #threshold;
+    #windowMs;
+    #resetMs;
+    #now;
+    #state = 'closed';
+    #openedAt = 0;
+    /** Timestamps, newest last. Trimmed on read, so an idle breaker costs nothing. */
+    #failures = [];
+    #successes = [];
+    constructor(options = {}, now = Date.now) {
+        this.#threshold = options.errorThreshold ?? DEFAULTS.errorThreshold;
+        this.#windowMs = options.windowMs ?? DEFAULTS.windowMs;
+        this.#resetMs = options.resetMs ?? DEFAULTS.resetMs;
+        this.#now = now;
+    }
+    get state() {
+        return this.#state;
+    }
+    /**
+     * Whether to attempt the call.
+     *
+     * Moves the breaker to half-open as a side effect once the reset has elapsed,
+     * so exactly one caller gets through to find out whether the service is back.
+     */
+    allows() {
+        if (this.#state === 'closed')
+            return true;
+        if (this.#state === 'open' && this.#now() - this.#openedAt >= this.#resetMs) {
+            this.#state = 'half_open';
+            return true;
+        }
+        return false;
+    }
+    succeeded() {
+        if (this.#state === 'half_open') {
+            // The probe came back. Start clean rather than carrying the failures that
+            // opened the circuit, or the next single error reopens it immediately.
+            this.#state = 'closed';
+            this.#failures = [];
+            this.#successes = [];
+            return;
+        }
+        this.#successes.push(this.#now());
+        this.#trim();
+    }
+    failed() {
+        if (this.#state === 'half_open') {
+            this.#open();
+            return;
+        }
+        this.#failures.push(this.#now());
+        this.#trim();
+        const total = this.#failures.length + this.#successes.length;
+        if (total >= MIN_CALLS && this.#failures.length / total >= this.#threshold)
+            this.#open();
+    }
+    #open() {
+        this.#state = 'open';
+        this.#openedAt = this.#now();
+        this.#failures = [];
+        this.#successes = [];
+    }
+    #trim() {
+        const cutoff = this.#now() - this.#windowMs;
+        this.#failures = this.#failures.filter((at) => at > cutoff);
+        this.#successes = this.#successes.filter((at) => at > cutoff);
+    }
+}
+//# sourceMappingURL=breaker.js.map

package/dist/client.d.ts

@@ -0,0 +1,100 @@
+import { Decision } from '@magield/proto';
+import { type BreakerOptions } from './breaker.js';
+import type { DecisionName, EvaluateInput, FeedbackInput, LimitCheckInput, LimitVerdict, TrustDeviceInput, TrustedDevice, Verdict } from './types.js';
+/**
+ * The backend client.
+ *
+ * Magic Shield is never called from a browser. This runs on the integrator's
+ * server, holds the API key, and is the only thing that talks to the gateway.
+ *
+ * It exists because five places in this repository already hand-rolled it and
+ * each got a different subset right — one set keepalive, none used the
+ * documented deadline, four retyped the metadata key, and not one implemented
+ * retry, a breaker or connection reuse. `docs/api.md` §5 says "the integrator
+ * should never have to think about any of it", and that only becomes true when
+ * it lives somewhere.
+ *
+ * Nothing here throws into a sign-in. A transport failure produces a verdict
+ * that says so, and the policy for what to do about it is configuration rather
+ * than an exception somebody has to remember to catch.
+ */
+export declare const API_KEY_METADATA = "x-mshield-api-key";
+export interface ShieldDefaults {
+    /**
+     * Per-call deadline. `docs/api.md` §5 says 40 ms, and means it — the pipeline
+     * targets a p99 of 12 ms in-process, so a deadline an order of magnitude
+     * above that is measuring the network, not the engine.
+     */
+    readonly deadlineMs?: number;
+    /**
+     * What an unreachable gateway means.
+     *
+     * `true` by default, and this is the most consequential line in the file: it
+     * decides what happens to somebody else's sign-in page when this service is
+     * down. Magic Shield must never be the reason a site is unavailable.
+     */
+    readonly failOpen?: boolean;
+    /** The decision a fail-open verdict carries. Not `allow`, so it is visible. */
+    readonly failOpenDecision?: DecisionName;
+    /** Attempts per call, including the first. */
+    readonly maxAttempts?: number;
+}
+export interface ShieldConfig {
+    /** `host:port` of the gateway. Internal only — it must not be public. */
+    readonly target: string;
+    readonly apiKey: string;
+    /** The application these calls are for. Checked against the key's binding. */
+    readonly appId: string;
+    /**
+     * Server TLS. `false` is plaintext and is for local development only.
+     *
+     * A PEM string or a path, matching what the gateway itself accepts.
+     */
+    readonly tls?: {
+        readonly ca?: string | Buffer;
+    } | false;
+    readonly defaults?: ShieldDefaults;
+    readonly breaker?: BreakerOptions;
+    /**
+     * Where failures go.
+     *
+     * A callback rather than a thrown error, the same choice the web SDK makes:
+     * there is no path out of this API that throws into an integrator's request
+     * handler, so the errors have to arrive somewhere else.
+     */
+    readonly onError?: (error: Error) => void;
+}
+export declare class ShieldClient {
+    #private;
+    constructor(config: ShieldConfig);
+    /**
+     * Scores a request.
+     *
+     * Never throws. When the gateway cannot answer, the verdict says `degraded`
+     * and carries the configured fail-open decision, so the calling code is the
+     * same on the good path and the bad one.
+     */
+    evaluate(input: EvaluateInput): Promise<Verdict>;
+    /**
+     * Reports what happened after a decision.
+     *
+     * Prefer `verdict.reportOutcome`, which cannot lose the `evaluationId`. This
+     * exists for the case where the verdict was not kept — a worker reconciling
+     * yesterday's chargebacks, say.
+     */
+    feedback(input: FeedbackInput): Promise<void>;
+    /** Enrols a device so it can earn trust. */
+    trustDevice(input: TrustDeviceInput): Promise<TrustedDevice>;
+    /**
+     * Asks the limiter directly, without scoring.
+     *
+     * For the endpoints that have a budget but no risk question — an export, a
+     * password-reset email, anything where the answer is "how often" rather than
+     * "who".
+     */
+    limitCheck(input: LimitCheckInput): Promise<LimitVerdict>;
+    close(): void;
+}
+export declare function createClient(config: ShieldConfig): ShieldClient;
+export { Decision };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,407 @@
+import { randomUUID } from 'node:crypto';
+import { credentials, Metadata, status } from '@grpc/grpc-js';
+import { CheckMode, CheckRequest, Decision, DevicesClient, EvaluateRequest, EvaluationClient, FeedbackRequest, LimitsClient, TrustRequest, TrustState, } from '@magield/proto';
+import { Breaker } from './breaker.js';
+import { decisionName, modeName, outcomeValue } from './decisions.js';
+/**
+ * The backend client.
+ *
+ * Magic Shield is never called from a browser. This runs on the integrator's
+ * server, holds the API key, and is the only thing that talks to the gateway.
+ *
+ * It exists because five places in this repository already hand-rolled it and
+ * each got a different subset right — one set keepalive, none used the
+ * documented deadline, four retyped the metadata key, and not one implemented
+ * retry, a breaker or connection reuse. `docs/api.md` §5 says "the integrator
+ * should never have to think about any of it", and that only becomes true when
+ * it lives somewhere.
+ *
+ * Nothing here throws into a sign-in. A transport failure produces a verdict
+ * that says so, and the policy for what to do about it is configuration rather
+ * than an exception somebody has to remember to catch.
+ */
+export const API_KEY_METADATA = 'x-mshield-api-key';
+const DEFAULT_DEADLINE_MS = 40;
+const DEFAULT_MAX_ATTEMPTS = 2;
+/** Retried. Both mean the call did not produce a decision. */
+const RETRYABLE = new Set([status.UNAVAILABLE, status.DEADLINE_EXCEEDED]);
+export class ShieldClient {
+    #evaluation;
+    #devices;
+    #limits;
+    #metadata;
+    #breaker;
+    #config;
+    constructor(config) {
+        this.#config = config;
+        // One long-lived Metadata, built once. Four of the five hand-rolled clients
+        // in this repository build a fresh one per call and retype the key.
+        this.#metadata = new Metadata();
+        this.#metadata.set(API_KEY_METADATA, config.apiKey);
+        const channel = this.#credentials();
+        const options = {
+            // Proven out by the edge collector, which is the one existing client that
+            // holds a connection open long enough to need them.
+            'grpc.keepalive_time_ms': 30_000,
+            'grpc.keepalive_timeout_ms': 10_000,
+            'grpc.keepalive_permit_without_calls': 1,
+            'grpc.max_receive_message_length': 4 * 1024 * 1024,
+        };
+        // Three clients, and grpc-js pools the underlying subchannel by target and
+        // credentials — so this is one connection, not three.
+        this.#evaluation = new EvaluationClient(config.target, channel, options);
+        this.#devices = new DevicesClient(config.target, channel, options);
+        this.#limits = new LimitsClient(config.target, channel, options);
+        this.#breaker = new Breaker(config.breaker ?? {});
+    }
+    /**
+     * Scores a request.
+     *
+     * Never throws. When the gateway cannot answer, the verdict says `degraded`
+     * and carries the configured fail-open decision, so the calling code is the
+     * same on the good path and the bad one.
+     */
+    async evaluate(input) {
+        const requestId = input.requestId ?? randomUUID();
+        try {
+            const response = await this.#call((metadata, options, callback) => this.#evaluation.evaluate(this.#evaluateRequest(input, requestId), metadata, options, callback), input.deadlineMs);
+            return this.#verdict(response);
+        }
+        catch (err) {
+            return this.#failOpen(err);
+        }
+    }
+    /**
+     * Reports what happened after a decision.
+     *
+     * Prefer `verdict.reportOutcome`, which cannot lose the `evaluationId`. This
+     * exists for the case where the verdict was not kept — a worker reconciling
+     * yesterday's chargebacks, say.
+     */
+    async feedback(input) {
+        // One of the two has to name a decision. Sending neither would be a call
+        // that returns 200 and can never be joined to anything — the exact silent
+        // failure this path is built to prevent.
+        if ((input.evaluationId ?? '') === '' && (input.requestId ?? '') === '') {
+            this.#config.onError?.(new Error('feedback needs evaluationId or requestId: an outcome that names no decision is lost'));
+            return;
+        }
+        try {
+            await this.#call((metadata, options, callback) => this.#evaluation.feedback(FeedbackRequest.fromPartial({
+                evaluationId: input.evaluationId ?? '',
+                requestId: input.requestId ?? '',
+                outcome: outcomeValue(input.outcome),
+                note: input.note ?? '',
+                metadata: { ...(input.metadata ?? {}) },
+                occurredAtMs: input.occurredAtMs ?? Date.now(),
+                action: input.action ?? '',
+                ...(input.keys === undefined ? {} : { keys: identifiers(input.keys) }),
+            }), metadata, options, callback), undefined);
+        }
+        catch (err) {
+            // Swallowed on purpose. A sign-in that already worked must not fail
+            // because a bookkeeping call did.
+            this.#config.onError?.(err);
+        }
+    }
+    /** Enrols a device so it can earn trust. */
+    async trustDevice(input) {
+        const device = await this.#call((metadata, options, callback) => this.#devices.trust(TrustRequest.fromPartial({
+            token: Buffer.from(input.deviceId, 'utf8'),
+            publicKey: input.publicKey,
+            authContext: input.authContext ?? '',
+            userId: '',
+            label: '',
+            ttlDays: 0,
+            stableCore: '',
+        }), metadata, options, callback), undefined);
+        return {
+            deviceId: device.deviceId,
+            state: (TrustState[device.state] ?? 'TRUST_STATE_UNSPECIFIED').replace(/^TRUST_STATE_/, '').toLowerCase(),
+            trustedAtMs: device.firstSeenMs,
+            lastSeenMs: device.lastSeenMs,
+        };
+    }
+    /**
+     * Asks the limiter directly, without scoring.
+     *
+     * For the endpoints that have a budget but no risk question — an export, a
+     * password-reset email, anything where the answer is "how often" rather than
+     * "who".
+     */
+    async limitCheck(input) {
+        try {
+            const response = await this.#call((metadata, options, callback) => this.#limits.check(CheckRequest.fromPartial({
+                appId: input.appId ?? this.#config.appId,
+                action: input.action,
+                mode: input.peek === true ? CheckMode.CHECK_MODE_PEEK : CheckMode.CHECK_MODE_CONSUME,
+                limitIds: [],
+                cost: 1,
+                ...(input.keys === undefined ? {} : { keys: identifiers(input.keys) }),
+                ...(input.ip === undefined ? {} : { network: networkContext({ ip: input.ip }) }),
+            }), metadata, options, callback), undefined);
+            return {
+                allowed: response.allowed,
+                decision: decisionName(response.decision),
+                retryAfterMs: Number(response.retryAfterMs),
+                limits: response.limits.map(limitState),
+            };
+        }
+        catch (err) {
+            this.#config.onError?.(err);
+            // Fail open, for the reason the limiter itself does: counters that
+            // rebuild are not worth refusing traffic over.
+            return { allowed: true, decision: 'allow_flagged', retryAfterMs: 0, limits: [] };
+        }
+    }
+    close() {
+        this.#evaluation.close();
+        this.#devices.close();
+        this.#limits.close();
+    }
+    /**
+     * One call, with the breaker, the deadline and the retry around it.
+     *
+     * The retry is only safe because the gateway deduplicates on `request_id` for
+     * sixty seconds. Before that window existed, a retry re-ran the pipeline and
+     * spent rate-limit budget a second time — so the documented behaviour was the
+     * unsafe one, and this client could not have honoured it.
+     */
+    async #call(invoke, deadlineMs) {
+        if (!this.#breaker.allows()) {
+            throw Object.assign(new Error('circuit open'), { code: status.UNAVAILABLE });
+        }
+        const budget = deadlineMs ?? this.#config.defaults?.deadlineMs ?? DEFAULT_DEADLINE_MS;
+        const attempts = this.#config.defaults?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        let last;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            if (attempt > 0)
+                await sleep(backoffMs(attempt));
+            try {
+                const value = await new Promise((resolve, reject) => {
+                    invoke(this.#metadata, { deadline: Date.now() + budget }, (err, response) => {
+                        if (err)
+                            reject(err);
+                        else
+                            resolve(response);
+                    });
+                });
+                this.#breaker.succeeded();
+                return value;
+            }
+            catch (err) {
+                last = err;
+                this.#breaker.failed();
+                if (!RETRYABLE.has(last.code ?? status.UNKNOWN))
+                    break;
+            }
+        }
+        throw last ?? new Error('no attempt was made');
+    }
+    #evaluateRequest(input, requestId) {
+        // Built here so `Exact<>` never reaches an integrator. The generated
+        // `fromPartial` only infers from an object literal at the call site, which
+        // is why every hand-rolled client in this repository writes one inline.
+        return EvaluateRequest.fromPartial({
+            requestId,
+            appId: input.appId ?? this.#config.appId,
+            action: input.action,
+            token: Buffer.from(input.token ?? '', 'utf8'),
+            context: { ...(input.context ?? {}) },
+            ...(input.keys === undefined ? {} : { keys: identifiers(input.keys) }),
+            ...(input.network === undefined && input.ip === undefined
+                ? {}
+                : { network: networkContext({ ip: input.ip, ...input.network }) }),
+            ...(input.solution === undefined
+                ? {}
+                : {
+                    solution: {
+                        challengeId: '',
+                        blob: Buffer.from(input.solution.blob, 'utf8'),
+                        // The proto calls it `solution`; the web SDK calls it `nonce`.
+                        // Translating here is the whole reason this method exists.
+                        solution: Buffer.from(input.solution.nonce, 'utf8'),
+                        solveMs: input.solution.solveMs,
+                    },
+                }),
+            ...(input.verboseReasons === true
+                ? { options: { verboseReasons: true, includeFingerprints: false, peek: false, modeOverride: 0 } }
+                : {}),
+        });
+    }
+    #verdict(response) {
+        const decision = decisionName(response.decision);
+        const client = this;
+        const base = {
+            evaluationId: response.evaluationId,
+            score: response.score,
+            confidence: response.confidence,
+            reasons: response.reasons.map((reason) => ({
+                code: reason.code,
+                dimension: reason.dimension,
+                weight: reason.weight,
+                confidence: reason.confidence,
+                message: reason.message,
+                ...(Object.keys(reason.detail).length === 0 ? {} : { detail: reason.detail }),
+            })),
+            subscores: response.subscores,
+            limits: response.limits.map(limitState),
+            degraded: response.degraded,
+            deviceId: response.deviceId,
+            modeApplied: modeName(response.modeApplied),
+            ...(response.wouldHave === undefined
+                ? {}
+                : { wouldHave: { decision: decisionName(response.wouldHave.decision), score: response.wouldHave.score } }),
+            async reportOutcome(outcome, extra = {}) {
+                await client.feedback({ evaluationId: response.evaluationId, outcome, ...extra });
+            },
+        };
+        if (decision === 'challenge' && response.challenge !== undefined) {
+            return {
+                ...base,
+                decision,
+                challenge: {
+                    blob: Buffer.from(response.challenge.blob).toString('utf8'),
+                    difficulty: response.challenge.difficulty,
+                    // Zero means one, which is what an older gateway issues.
+                    subtasks: response.challenge.subtasks === 0 ? 1 : response.challenge.subtasks,
+                    algorithm: response.challenge.algorithm === '' ? 'sha256' : response.challenge.algorithm,
+                    expectedMs: response.challenge.expectedMs,
+                    ttlMs: response.challenge.ttlMs,
+                },
+            };
+        }
+        if (decision === 'throttle')
+            return { ...base, decision, retryAfterMs: response.retryAfterMs };
+        // A challenge decision with no challenge cannot reach here — the gateway
+        // downgrades to `allow_flagged` when it cannot issue one — but the cast
+        // would be a lie if it ever did, so it is read as the safe neighbour.
+        return { ...base, decision: decision === 'challenge' ? 'allow_flagged' : decision };
+    }
+    /**
+     * The verdict for a call that never produced one.
+     *
+     * `evaluationId` is empty, so `reportOutcome` is a no-op: there is no
+     * decision to join an outcome to, and recording one against nothing would
+     * corrupt the very measurement outcomes exist to feed.
+     */
+    #failOpen(err) {
+        this.#config.onError?.(err);
+        if (this.#config.defaults?.failOpen === false)
+            throw err;
+        /*
+         * Failing open on a misconfiguration still fails open — and says so.
+         *
+         * Every error took this path and every one of them came back as
+         * `MSHIELD_UNAVAILABLE`, "the gateway could not be reached". For a down
+         * gateway that is true. For a wrong API key, a key bound to another
+         * `appId`, or a malformed field it is a lie, and an expensive one: the
+         * integration appears to work, allows everything, scores nothing, and
+         * keeps doing so until somebody notices the console is empty. A
+         * misconfigured deployment that looks healthy is the worst outcome this
+         * SDK can produce.
+         *
+         * Still fail open, because the alternative is taking somebody's sign-in
+         * page down over a configuration mistake. But name it correctly, so
+         * `onError`, the reason code and any alert built on either tell the truth.
+         */
+        const misconfigured = err.code === status.UNAUTHENTICATED ||
+            err.code === status.PERMISSION_DENIED ||
+            err.code === status.INVALID_ARGUMENT;
+        return {
+            evaluationId: '',
+            decision: this.#config.defaults?.failOpenDecision ?? 'allow_flagged',
+            score: 0,
+            confidence: 0,
+            reasons: [
+                {
+                    code: misconfigured ? 'MSHIELD_MISCONFIGURED' : 'MSHIELD_UNAVAILABLE',
+                    dimension: 'none',
+                    weight: 0,
+                    confidence: 0,
+                    message: misconfigured
+                        ? `this call was refused and will keep being refused until it is fixed: ${err.message}`
+                        : `the gateway could not be reached: ${err.message}`,
+                },
+            ],
+            subscores: {},
+            limits: [],
+            degraded: true,
+            deviceId: '',
+            modeApplied: 'unspecified',
+            reportOutcome: async () => undefined,
+        };
+    }
+    #credentials() {
+        const tls = this.#config.tls;
+        if (tls === false || tls === undefined)
+            return credentials.createInsecure();
+        return tls.ca === undefined
+            ? credentials.createSsl()
+            : credentials.createSsl(typeof tls.ca === 'string' ? Buffer.from(tls.ca, 'utf8') : tls.ca);
+    }
+}
+export function createClient(config) {
+    return new ShieldClient(config);
+}
+/** Full jitter. Two clients retrying in step is how a recovering service stays down. */
+function backoffMs(attempt) {
+    return Math.random() * Math.min(100, 2 ** attempt * 20);
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+function identifiers(keys) {
+    return {
+        username: keys.username ?? '',
+        userId: keys.userId ?? '',
+        email: keys.email ?? '',
+        phone: keys.phone ?? '',
+        sessionId: keys.sessionId ?? '',
+        apiKeyId: keys.apiKeyId ?? '',
+        passwordSha1Prefix: keys.passwordSha1Prefix ?? '',
+        custom: { ...(keys.custom ?? {}) },
+    };
+}
+function networkContext(network) {
+    return {
+        ip: network.ip ?? '',
+        forwardedFor: network.forwardedFor ?? '',
+        ja4: network.ja4 ?? '',
+        ja4s: '',
+        ja3: network.ja3 ?? '',
+        http2Fp: '',
+        tcpFp: '',
+        headerOrder: [...(network.headerOrder ?? [])],
+        headers: {
+            ...(network.headers ?? {}),
+            ...(network.userAgent === undefined ? {} : { 'user-agent': network.userAgent }),
+        },
+        tlsVersion: '',
+        tlsCipher: '',
+        tlsResumed: false,
+        httpVersion: '',
+        clientTcpRttMs: 0,
+        source: 0,
+        cfBotScore: 0,
+        cfVerifiedBot: false,
+    };
+}
+function limitState(state) {
+    // int64 fields arrive as plain numbers here, but every hand-rolled client in
+    // this repository coerces them anyway because the generated type says so.
+    return {
+        id: state.id,
+        limit: Number(state.limit),
+        remaining: Number(state.remaining),
+        resetAtMs: Number(state.resetAtMs),
+        exceeded: state.exceeded,
+        shadow: state.shadow,
+        keyPreview: state.keyPreview,
+    };
+}
+export { Decision };
+//# sourceMappingURL=client.js.map

package/dist/decisions.d.ts

@@ -0,0 +1,17 @@
+import { Decision, Mode, Outcome } from '@magield/proto';
+import type { DecisionName, OutcomeName } from './types.js';
+/**
+ * Reads a decision off the wire.
+ *
+ * `DECISION_UNSPECIFIED` and anything this build has never heard of both become
+ * `allow_flagged`: let it through, and record that something was there. Mapping
+ * an unknown decision to `allow` would discard a signal the gateway meant to
+ * send; mapping it to `deny` would block real people because a server was
+ * upgraded first. `allow_flagged` is the reading that is wrong in the smallest
+ * way in either direction.
+ */
+export declare function decisionName(decision: Decision): DecisionName;
+export declare function outcomeValue(outcome: OutcomeName): Outcome;
+/** For display and logging only. Never compared against. */
+export declare function modeName(mode: Mode): string;
+//# sourceMappingURL=decisions.d.ts.map