@magield/node 0.0.0-stage → 0.7.1

package/dist/decisions.js

@@ -0,0 +1,60 @@
+import { Decision, Mode, Outcome } from '@magield/proto';
+/**
+ * The only place two spellings of the same thing exist.
+ *
+ * The wire uses fully prefixed enum names — `DECISION_ALLOW_FLAGGED`,
+ * `OUTCOME_LOGIN_SUCCESS` — and `docs/api.md` §5 publishes the short lower-case
+ * form to integrators. Both are right for their audience and neither should
+ * leak into the other's, so the translation happens once, here.
+ *
+ * The generated `decisionToJSON` and `outcomeToJSON` are deliberately not used.
+ * They **throw** on a value they do not recognise, which is the wrong behaviour
+ * for a client: a gateway one minor version ahead that adds a decision would
+ * crash an older SDK rather than degrade. Additive changes within `v1` are
+ * promised (`docs/api.md` §7), so an unknown decision is a thing that will
+ * happen, and the safe reading of one is the most conservative neighbour rather
+ * than an exception thrown into somebody's sign-in.
+ */
+const DECISIONS = new Map([
+    [Decision.DECISION_ALLOW, 'allow'],
+    [Decision.DECISION_ALLOW_FLAGGED, 'allow_flagged'],
+    [Decision.DECISION_CHALLENGE, 'challenge'],
+    [Decision.DECISION_STEP_UP, 'step_up'],
+    [Decision.DECISION_THROTTLE, 'throttle'],
+    [Decision.DECISION_DENY, 'deny'],
+    [Decision.DECISION_BAN, 'ban'],
+]);
+/**
+ * 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 function decisionName(decision) {
+    return DECISIONS.get(decision) ?? 'allow_flagged';
+}
+const OUTCOMES = new Map([
+    ['login_success', Outcome.OUTCOME_LOGIN_SUCCESS],
+    ['login_failure', Outcome.OUTCOME_LOGIN_FAILURE],
+    ['mfa_success', Outcome.OUTCOME_MFA_SUCCESS],
+    ['mfa_failure', Outcome.OUTCOME_MFA_FAILURE],
+    ['confirmed_good', Outcome.OUTCOME_CONFIRMED_GOOD],
+    ['confirmed_fraud', Outcome.OUTCOME_CONFIRMED_FRAUD],
+    ['chargeback', Outcome.OUTCOME_CHARGEBACK],
+    ['manual_review_good', Outcome.OUTCOME_MANUAL_REVIEW_GOOD],
+    ['manual_review_bad', Outcome.OUTCOME_MANUAL_REVIEW_BAD],
+    ['user_complaint', Outcome.OUTCOME_USER_COMPLAINT],
+    ['support_unblock', Outcome.OUTCOME_SUPPORT_UNBLOCK],
+]);
+export function outcomeValue(outcome) {
+    return OUTCOMES.get(outcome) ?? Outcome.OUTCOME_UNSPECIFIED;
+}
+/** For display and logging only. Never compared against. */
+export function modeName(mode) {
+    return (Mode[mode] ?? 'MODE_UNSPECIFIED').replace(/^MODE_/, '').toLowerCase();
+}
+//# sourceMappingURL=decisions.js.map

package/dist/express.d.ts

@@ -0,0 +1,69 @@
+import type { ShieldClient } from './client.js';
+import type { EvaluateInput } from './types.js';
+/**
+ * Express middleware.
+ *
+ * Opt-in and explicit, per `PLAN.md` §4.2, and behind its own subpath so
+ * importing the client pulls none of this in.
+ *
+ * **It enforces nothing.** It scores the request, attaches the verdict, and
+ * calls `next()`. That is not laziness — it is the product's central claim:
+ * the engine advises and the integrator enforces, because what a denial should
+ * do to *your* sign-in page is a decision only you can make. A middleware that
+ * returned 403 on its own would be taking it.
+ *
+ * ## Why the types are structural
+ *
+ * Express is not a dependency of this package, and nor are its types. The three
+ * properties used here are the three declared below, so this works against
+ * Express 4 and 5 without pinning either, and a partner on a fork or a
+ * compatible router is not excluded by a version range we had no reason to
+ * pick.
+ */
+/** The three things this middleware touches. */
+export interface ExpressRequestLike {
+    readonly body?: unknown;
+    readonly ip?: string | undefined;
+    readonly headers: Record<string, string | string[] | undefined>;
+    [key: string]: unknown;
+}
+export type ExpressNext = (err?: unknown) => void;
+export interface ShieldMiddlewareOptions {
+    readonly action: string;
+    /** Pulls the sealed token off the request. Defaults to `body.shieldToken`. */
+    readonly token?: (req: ExpressRequestLike) => string | undefined;
+    /** Business identifiers for this request. */
+    readonly keys?: (req: ExpressRequestLike) => EvaluateInput['keys'];
+    /**
+     * Where to hang the verdict. `req.shield` by default.
+     *
+     * Named rather than fixed because a property this middleware invents on
+     * somebody else's request object can collide, and silently.
+     */
+    readonly property?: string;
+}
+/**
+ * Scores the request and attaches the verdict.
+ *
+ * ```ts
+ * app.post('/login', shieldExpress(shield, {
+ *   action: 'login',
+ *   keys: (req) => ({ username: (req.body as { username?: string }).username }),
+ * }), (req, res) => {
+ *   const verdict = (req as { shield: Verdict }).shield
+ *   if (verdict.decision === 'deny') return res.status(401).json({ error: 'try again' })
+ *   if (verdict.decision === 'challenge') return res.status(401).json({ challenge: verdict.challenge })
+ *   // …sign them in, then: await verdict.reportOutcome('login_success')
+ * })
+ * ```
+ */
+export declare function shieldExpress(shield: ShieldClient, options: ShieldMiddlewareOptions): (req: ExpressRequestLike, res: unknown, next: ExpressNext) => void;
+/**
+ * Flattens the header bag.
+ *
+ * Node gives repeated headers as an array; the wire wants one string each. The
+ * order is preserved because header *order* is itself a signal — a browser
+ * sends its headers in a stable order and a script usually does not.
+ */
+export declare function stringHeaders(headers: Record<string, string | string[] | undefined>): Record<string, string>;
+//# sourceMappingURL=express.d.ts.map

package/dist/express.js

@@ -0,0 +1,59 @@
+/**
+ * Scores the request and attaches the verdict.
+ *
+ * ```ts
+ * app.post('/login', shieldExpress(shield, {
+ *   action: 'login',
+ *   keys: (req) => ({ username: (req.body as { username?: string }).username }),
+ * }), (req, res) => {
+ *   const verdict = (req as { shield: Verdict }).shield
+ *   if (verdict.decision === 'deny') return res.status(401).json({ error: 'try again' })
+ *   if (verdict.decision === 'challenge') return res.status(401).json({ challenge: verdict.challenge })
+ *   // …sign them in, then: await verdict.reportOutcome('login_success')
+ * })
+ * ```
+ */
+export function shieldExpress(shield, options) {
+    const property = options.property ?? 'shield';
+    return (req, _res, next) => {
+        // `void` rather than `async`: an express middleware that returns a promise
+        // has its rejection swallowed by the router, and `evaluate` does not reject
+        // anyway — a failure arrives as a degraded verdict.
+        void shield
+            .evaluate({
+            action: options.action,
+            ...(defaultToken(req, options) === undefined ? {} : { token: defaultToken(req, options) }),
+            ...(options.keys === undefined ? {} : { keys: options.keys(req) }),
+            ...(req.ip === undefined ? {} : { ip: req.ip }),
+            network: { headers: stringHeaders(req.headers) },
+        })
+            .then((verdict) => {
+            ;
+            req[property] = verdict;
+            next();
+        });
+    };
+}
+function defaultToken(req, options) {
+    if (options.token !== undefined)
+        return options.token(req);
+    const body = req.body;
+    return typeof body?.shieldToken === 'string' ? body.shieldToken : undefined;
+}
+/**
+ * Flattens the header bag.
+ *
+ * Node gives repeated headers as an array; the wire wants one string each. The
+ * order is preserved because header *order* is itself a signal — a browser
+ * sends its headers in a stable order and a script usually does not.
+ */
+export function stringHeaders(headers) {
+    const flat = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        flat[name] = Array.isArray(value) ? value.join(', ') : value;
+    }
+    return flat;
+}
+//# sourceMappingURL=express.js.map

package/dist/fastify.d.ts

@@ -0,0 +1,39 @@
+import type { ShieldClient } from './client.js';
+import type { EvaluateInput } from './types.js';
+/**
+ * A Fastify preHandler.
+ *
+ * Same contract as the Express adapter and the same reasoning: it scores,
+ * attaches, and enforces nothing. Fastify is not a dependency and its types are
+ * not imported — the four properties used are declared below, so this works
+ * against Fastify 4 and 5 alike.
+ *
+ * A `preHandler` rather than a plugin, deliberately. A plugin would have to
+ * decorate the request and register hooks for routes it cannot know about; a
+ * preHandler is attached to the one route that needs it, which is where the
+ * decision about what to score belongs.
+ */
+export interface FastifyRequestLike {
+    readonly body?: unknown;
+    readonly ip?: string;
+    readonly headers: Record<string, string | string[] | undefined>;
+    [key: string]: unknown;
+}
+export interface ShieldPreHandlerOptions {
+    readonly action: string;
+    readonly token?: (req: FastifyRequestLike) => string | undefined;
+    readonly keys?: (req: FastifyRequestLike) => EvaluateInput['keys'];
+    /** Where to hang the verdict. `request.shield` by default. */
+    readonly property?: string;
+}
+/**
+ * ```ts
+ * fastify.post('/login', { preHandler: shieldFastify(shield, { action: 'login' }) }, async (req, reply) => {
+ *   const verdict = (req as { shield: Verdict }).shield
+ *   if (verdict.decision === 'deny') return reply.code(401).send({ error: 'try again' })
+ *   …
+ * })
+ * ```
+ */
+export declare function shieldFastify(shield: ShieldClient, options: ShieldPreHandlerOptions): (req: FastifyRequestLike) => Promise<void>;
+//# sourceMappingURL=fastify.d.ts.map

package/dist/fastify.js

@@ -0,0 +1,29 @@
+import { stringHeaders } from './express.js';
+/**
+ * ```ts
+ * fastify.post('/login', { preHandler: shieldFastify(shield, { action: 'login' }) }, async (req, reply) => {
+ *   const verdict = (req as { shield: Verdict }).shield
+ *   if (verdict.decision === 'deny') return reply.code(401).send({ error: 'try again' })
+ *   …
+ * })
+ * ```
+ */
+export function shieldFastify(shield, options) {
+    const property = options.property ?? 'shield';
+    return async (req) => {
+        const token = options.token !== undefined ? options.token(req) : bodyToken(req);
+        const verdict = await shield.evaluate({
+            action: options.action,
+            ...(token === undefined ? {} : { token }),
+            ...(options.keys === undefined ? {} : { keys: options.keys(req) }),
+            ...(req.ip === undefined ? {} : { ip: req.ip }),
+            network: { headers: stringHeaders(req.headers) },
+        });
+        req[property] = verdict;
+    };
+}
+function bodyToken(req) {
+    const body = req.body;
+    return typeof body?.shieldToken === 'string' ? body.shieldToken : undefined;
+}
+//# sourceMappingURL=fastify.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createClient, ShieldClient, API_KEY_METADATA } from './client.js';
+export type { ShieldConfig, ShieldDefaults } from './client.js';
+export { passwordPrefix, isPasswordPrefix } from './password.js';
+export { Breaker } from './breaker.js';
+export type { BreakerOptions } from './breaker.js';
+export type { ChallengeOffer, ChallengeSolution, DecisionName, EvaluateInput, FeedbackInput, Identifiers, LimitCheckInput, LimitState, LimitVerdict, NetworkContext, OutcomeDetails, OutcomeName, Reason, TrustDeviceInput, TrustedDevice, Verdict, WouldHave, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createClient, ShieldClient, API_KEY_METADATA } from './client.js';
+export { passwordPrefix, isPasswordPrefix } from './password.js';
+export { Breaker } from './breaker.js';
+//# sourceMappingURL=index.js.map

package/dist/nest.d.ts

@@ -0,0 +1,45 @@
+import type { ShieldClient } from './client.js';
+import type { EvaluateInput } from './types.js';
+/**
+ * A NestJS guard.
+ *
+ * Nest is not a dependency and there are no decorators here, which is
+ * deliberate rather than a shortcut: a guard is structurally just an object
+ * with `canActivate`, and `@nestjs/common` would add a large dependency to buy
+ * a decorator the integrator can apply themselves with `@UseGuards(...)`.
+ *
+ * **It always returns true.** A Nest guard that returned false would send a
+ * 403 the integrator did not choose, which is precisely the enforcement this
+ * product leaves to them. The guard's job is to put the verdict on the request;
+ * the controller decides.
+ */
+interface ExecutionContextLike {
+    switchToHttp(): {
+        getRequest<T = Record<string, unknown>>(): T;
+    };
+}
+export interface ShieldGuardOptions {
+    readonly action: string;
+    readonly token?: (req: Record<string, unknown>) => string | undefined;
+    readonly keys?: (req: Record<string, unknown>) => EvaluateInput['keys'];
+    /** Where to hang the verdict. `request.shield` by default. */
+    readonly property?: string;
+}
+export interface ShieldGuard {
+    canActivate(context: ExecutionContextLike): Promise<boolean>;
+}
+/**
+ * ```ts
+ * const guard = createShieldGuard(shield, { action: 'login' })
+ *
+ * @UseGuards(guard)
+ * @Post('login')
+ * async login(@Req() req: Request & { shield: Verdict }) {
+ *   if (req.shield.decision === 'deny') throw new UnauthorizedException()
+ *   …
+ * }
+ * ```
+ */
+export declare function createShieldGuard(shield: ShieldClient, options: ShieldGuardOptions): ShieldGuard;
+export {};
+//# sourceMappingURL=nest.d.ts.map

package/dist/nest.js

@@ -0,0 +1,39 @@
+import { stringHeaders } from './express.js';
+/**
+ * ```ts
+ * const guard = createShieldGuard(shield, { action: 'login' })
+ *
+ * @UseGuards(guard)
+ * @Post('login')
+ * async login(@Req() req: Request & { shield: Verdict }) {
+ *   if (req.shield.decision === 'deny') throw new UnauthorizedException()
+ *   …
+ * }
+ * ```
+ */
+export function createShieldGuard(shield, options) {
+    const property = options.property ?? 'shield';
+    return {
+        async canActivate(context) {
+            const req = context.switchToHttp().getRequest();
+            const headers = (req['headers'] ?? {});
+            const ip = typeof req['ip'] === 'string' ? req['ip'] : undefined;
+            const token = options.token !== undefined ? options.token(req) : bodyToken(req);
+            const verdict = await shield.evaluate({
+                action: options.action,
+                ...(token === undefined ? {} : { token }),
+                ...(options.keys === undefined ? {} : { keys: options.keys(req) }),
+                ...(ip === undefined ? {} : { ip }),
+                network: { headers: stringHeaders(headers) },
+            });
+            req[property] = verdict;
+            // Never false. See the note above.
+            return true;
+        },
+    };
+}
+function bodyToken(req) {
+    const body = req['body'];
+    return typeof body?.shieldToken === 'string' ? body.shieldToken : undefined;
+}
+//# sourceMappingURL=nest.js.map

package/dist/password.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The first five hex characters of a password's SHA-1.
+ *
+ * `docs/rate-limiting.md` §175 promises this helper "so nobody hand-rolls the
+ * computation", and hand-rolling it is genuinely dangerous: the whole point is
+ * that five characters identify a *campaign* and identify no *person*. Send six
+ * and the space narrows by sixteen; send the full digest and you have shipped a
+ * password hash to a service that never asked for one.
+ *
+ * It is k-anonymity, the same construction Have I Been Pwned's range API uses.
+ * Five hex characters is one bucket in about a million, which is enough to see
+ * one password being sprayed across many accounts and far too coarse to say
+ * whose it was.
+ *
+ * **This is the only place the guardrail exists.** Both this document and the
+ * proto comment on `password_sha1_prefix` say the gateway rejects anything that
+ * is not exactly five lowercase hex characters. It does not — `services/
+ * context.ts` passes the field through on a truthiness check. Until that is
+ * fixed server-side, a caller that builds the prefix by hand can send whatever
+ * it likes and nothing will stop it.
+ */
+export declare function passwordPrefix(password: string): string;
+/** Whether a value is a prefix this SDK would have produced. */
+export declare function isPasswordPrefix(value: string): boolean;
+//# sourceMappingURL=password.d.ts.map

package/dist/password.js

@@ -0,0 +1,30 @@
+import { createHash } from 'node:crypto';
+/**
+ * The first five hex characters of a password's SHA-1.
+ *
+ * `docs/rate-limiting.md` §175 promises this helper "so nobody hand-rolls the
+ * computation", and hand-rolling it is genuinely dangerous: the whole point is
+ * that five characters identify a *campaign* and identify no *person*. Send six
+ * and the space narrows by sixteen; send the full digest and you have shipped a
+ * password hash to a service that never asked for one.
+ *
+ * It is k-anonymity, the same construction Have I Been Pwned's range API uses.
+ * Five hex characters is one bucket in about a million, which is enough to see
+ * one password being sprayed across many accounts and far too coarse to say
+ * whose it was.
+ *
+ * **This is the only place the guardrail exists.** Both this document and the
+ * proto comment on `password_sha1_prefix` say the gateway rejects anything that
+ * is not exactly five lowercase hex characters. It does not — `services/
+ * context.ts` passes the field through on a truthiness check. Until that is
+ * fixed server-side, a caller that builds the prefix by hand can send whatever
+ * it likes and nothing will stop it.
+ */
+export function passwordPrefix(password) {
+    return createHash('sha1').update(password, 'utf8').digest('hex').slice(0, 5);
+}
+/** Whether a value is a prefix this SDK would have produced. */
+export function isPasswordPrefix(value) {
+    return /^[0-9a-f]{5}$/.test(value);
+}
+//# sourceMappingURL=password.js.map