@magield/node 0.0.0-stage → 0.6.1

package/dist/types.d.ts

@@ -0,0 +1,273 @@
+/**
+ * What an integrator writes and reads.
+ *
+ * None of it is protobuf. That is the point of this file: the generated types
+ * are complete by definition, so every message has to be built whole, and
+ * `fromPartial` — the thing that fills the zeroes for you — is constrained by an
+ * `Exact<>` type that only infers correctly from an object literal written at
+ * the call site. Every hand-rolled client in this repository works around that
+ * the same way, by building the literal inline and passing a finished message
+ * around. An integrator should never meet it.
+ *
+ * So the shapes here are ordinary TypeScript. Strings are strings, the token is
+ * a string, `ip` is where somebody would look for it, and absent means absent.
+ */
+/**
+ * The verdict, in the vocabulary of `docs/api.md` §5.
+ *
+ * Lower case and unprefixed, because that is the published contract and because
+ * `DECISION_ALLOW_FLAGGED` is not a thing to read forty times in a switch. The
+ * mapping to the wire enum is in `decisions.ts` and is the only place either
+ * spelling appears.
+ */
+export type DecisionName = 'allow' | 'allow_flagged' | 'challenge' | 'step_up' | 'throttle' | 'deny' | 'ban';
+/**
+ * The eleven outcomes, in the short form `docs/api.md` §5 publishes.
+ *
+ * `confirmed_good` and `confirmed_fraud` are the two that matter most: they are
+ * what turns a decision into a labelled example, and without them there is no
+ * false-positive rate to measure and nothing to calibrate against.
+ */
+export type OutcomeName = 'login_success' | 'login_failure' | 'mfa_success' | 'mfa_failure' | 'confirmed_good' | 'confirmed_fraud' | 'chargeback' | 'manual_review_good' | 'manual_review_bad' | 'user_complaint' | 'support_unblock';
+/**
+ * Business identifiers, all optional.
+ *
+ * Send what the action actually has. A password reset knows an email and no
+ * username; a checkout knows a user id and no password. Nothing here is
+ * required and nothing is penalised for being absent — the engine scores what
+ * it is given.
+ *
+ * These are hashed with the tenant's salt before they reach any datastore, so
+ * a username never lands in a database, a log line or a metric label.
+ */
+export interface Identifiers {
+    readonly username?: string;
+    readonly userId?: string;
+    readonly email?: string;
+    readonly phone?: string;
+    readonly sessionId?: string;
+    readonly apiKeyId?: string;
+    /**
+     * The first five hex characters of the password's SHA-1, and nothing more.
+     *
+     * Use `passwordPrefix()` to compute it. It exists so a limit can notice one
+     * password being tried against many accounts without anyone holding the
+     * password — five characters is roughly a millionth of the space, which
+     * identifies a spraying campaign and identifies no individual.
+     */
+    readonly passwordSha1Prefix?: string;
+    readonly custom?: Readonly<Record<string, string>>;
+}
+/** What the socket revealed, when something in front of you observed it. */
+export interface NetworkContext {
+    readonly ip?: string;
+    readonly forwardedFor?: string;
+    readonly ja3?: string;
+    readonly ja4?: string;
+    readonly userAgent?: string;
+    readonly headerOrder?: readonly string[];
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface EvaluateInput {
+    /** `'login'`, `'signup'`, `'checkout'` — yours to name. */
+    readonly action: string;
+    /**
+     * The sealed string the web SDK returned.
+     *
+     * Absent is fine and is not an error: a missing token on a protected action
+     * is evidence (`TOK_ABSENT`) and produces a normal scored response. A page
+     * with JavaScript disabled is a real visitor, and refusing to decide about
+     * them would be the wrong answer to a question that has one.
+     */
+    readonly token?: string;
+    readonly keys?: Identifiers;
+    /** The caller's address. Convenience for `network.ip`, which is where it goes. */
+    readonly ip?: string;
+    readonly network?: NetworkContext;
+    /** Overrides the client's `appId` for this call. Rarely needed. */
+    readonly appId?: string;
+    /**
+     * Your own idempotency key.
+     *
+     * Generated when omitted. Supplying one lets you retry across process
+     * boundaries and get the original decision back rather than a second one —
+     * the gateway holds it for sixty seconds.
+     */
+    readonly requestId?: string;
+    /** A solved challenge, on the retry after one was issued. */
+    readonly solution?: ChallengeSolution;
+    /** Per-call deadline, overriding the client default. */
+    readonly deadlineMs?: number;
+    /** Ask for the `detail` map on each reason. Costs response size. */
+    readonly verboseReasons?: boolean;
+    /** Free-form context the rules can read. `origin` is the one that matters. */
+    readonly context?: Readonly<Record<string, string>>;
+}
+export interface ChallengeSolution {
+    readonly blob: string;
+    readonly nonce: string;
+    readonly solveMs: number;
+}
+/** A challenge to hand to the page. Opaque, sealed, and bound to this device. */
+export interface ChallengeOffer {
+    readonly blob: string;
+    readonly difficulty: number;
+    readonly subtasks: number;
+    readonly algorithm: string;
+    readonly expectedMs: number;
+    readonly ttlMs: number;
+}
+export interface Reason {
+    readonly code: string;
+    readonly dimension: string;
+    /** Negative weights exonerate. */
+    readonly weight: number;
+    readonly confidence: number;
+    readonly message: string;
+    readonly detail?: Readonly<Record<string, string>>;
+}
+export interface LimitState {
+    readonly id: string;
+    readonly limit: number;
+    readonly remaining: number;
+    readonly resetAtMs: number;
+    /** This limit is the reason for the decision, or would have been. */
+    readonly exceeded: boolean;
+    /** Evaluated and not enforced, so it can be tuned before it bites. */
+    readonly shadow: boolean;
+    /** Enough of the key to say which bucket, never the raw identifier. */
+    readonly keyPreview: string;
+}
+/** What the engine would have done if the mode had let it. */
+export interface WouldHave {
+    readonly decision: DecisionName;
+    readonly score: number;
+}
+interface VerdictBase {
+    /**
+     * The id this decision is recorded under.
+     *
+     * Carry it into `feedback`. Empty only on a fail-open verdict, where there is
+     * no decision to join anything to.
+     */
+    readonly evaluationId: string;
+    readonly score: number;
+    readonly confidence: number;
+    readonly reasons: readonly Reason[];
+    readonly subscores: Readonly<Record<string, number>>;
+    readonly limits: readonly LimitState[];
+    /** A stage failed open, so this decision was made with less than usual. */
+    readonly degraded: boolean;
+    /** Present when the mode softened the decision. The onboarding signal. */
+    readonly wouldHave?: WouldHave;
+    readonly deviceId: string;
+    readonly modeApplied: string;
+    /**
+     * Tells the engine what happened next.
+     *
+     * On the verdict rather than on the client, so the `evaluationId` cannot be
+     * dropped. Dropping it is a silent, structural failure: the outcome still
+     * arrives, still clears the limit counters a real user tripped with their own
+     * typos, and still looks like it worked — but it can never be joined to the
+     * decision it describes, so the false-positive rate it exists to measure
+     * reads a permanent zero. That was a real bug in this product's own demo, and
+     * nobody noticed until somebody went looking for the number.
+     *
+     * Fire and forget. A sign-in that already worked must not fail because a
+     * bookkeeping call did.
+     */
+    reportOutcome(outcome: OutcomeName, extra?: OutcomeDetails): Promise<void>;
+}
+export interface OutcomeDetails {
+    readonly note?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly occurredAtMs?: number;
+}
+/**
+ * The verdict, discriminated on the decision.
+ *
+ * `decision === 'challenge'` narrows `challenge` to defined, and nothing else
+ * does. That is not a convenience — it is an invariant the gateway guarantees
+ * by downgrading to `allow_flagged` when it cannot issue one, so encoding it in
+ * the type means a partner cannot write the branch that handles a challenge
+ * that is not there.
+ *
+ * `retryAfterMs` is narrowed the same way: it is zero on every decision but
+ * `throttle`, so only that member carries it.
+ */
+export type Verdict = (VerdictBase & {
+    readonly decision: 'challenge';
+    readonly challenge: ChallengeOffer;
+}) | (VerdictBase & {
+    readonly decision: 'throttle';
+    readonly retryAfterMs: number;
+}) | (VerdictBase & {
+    readonly decision: 'allow' | 'allow_flagged' | 'step_up' | 'deny' | 'ban';
+});
+export interface FeedbackInput {
+    /**
+     * The decision this outcome is about. Either this or `requestId`.
+     *
+     * Prefer `verdict.reportOutcome`, which carries it for you. Use this when
+     * the verdict is still in hand.
+     */
+    readonly evaluationId?: string;
+    /**
+     * Your own reference for the request, as sent on the Evaluate.
+     *
+     * This is the one to use for a label that arrives later — a chargeback, a
+     * manual review, an account closed for abuse. The alternative is keeping our
+     * `evaluationId` in your database on your own retention, and that is the
+     * step integrations skip; when it is skipped the outcome still arrives,
+     * still clears the limits, still returns 200, and joins to nothing for ever.
+     *
+     * So send the reference you already have. Pass your transaction's primary
+     * key as `requestId` on `evaluate` — it doubles as the idempotency key the
+     * field is named for — and send the same value back whenever the verdict is
+     * reached. Nothing of ours needs storing anywhere.
+     */
+    readonly requestId?: string;
+    readonly outcome: OutcomeName;
+    /**
+     * The action and identifiers the decision was about.
+     *
+     * Sent again rather than looked up, so reporting an outcome needs no
+     * server-side state between the two calls. They also drive `resetOn`: a
+     * limit a real user tripped is cleared by the success that proves they were
+     * entitled, and without these the reset is a silent no-op.
+     */
+    readonly action?: string;
+    readonly keys?: Identifiers;
+    readonly note?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly occurredAtMs?: number;
+}
+export interface TrustDeviceInput {
+    readonly deviceId: string;
+    readonly publicKey: string;
+    readonly appId?: string;
+    /** What justified the enrolment — a password, a second factor, a session. */
+    readonly authContext?: string;
+}
+export interface TrustedDevice {
+    readonly deviceId: string;
+    readonly state: string;
+    readonly trustedAtMs: number;
+    readonly lastSeenMs: number;
+}
+export interface LimitCheckInput {
+    readonly action: string;
+    readonly keys?: Identifiers;
+    readonly ip?: string;
+    readonly appId?: string;
+    /** Check without consuming budget. */
+    readonly peek?: boolean;
+}
+export interface LimitVerdict {
+    readonly allowed: boolean;
+    readonly decision: DecisionName;
+    readonly retryAfterMs: number;
+    readonly limits: readonly LimitState[];
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * What an integrator writes and reads.
+ *
+ * None of it is protobuf. That is the point of this file: the generated types
+ * are complete by definition, so every message has to be built whole, and
+ * `fromPartial` — the thing that fills the zeroes for you — is constrained by an
+ * `Exact<>` type that only infers correctly from an object literal written at
+ * the call site. Every hand-rolled client in this repository works around that
+ * the same way, by building the literal inline and passing a finished message
+ * around. An integrator should never meet it.
+ *
+ * So the shapes here are ordinary TypeScript. Strings are strings, the token is
+ * a string, `ip` is where somebody would look for it, and absent means absent.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@magield/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.1",
+  "description": "Magic Shield backend SDK",
+  "license": "SEE LICENSE IN LICENSE",
+  "files": [
+    "dist",
+    "!**/*.map",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./express": "./dist/express.js",
+    "./fastify": "./dist/fastify.js",
+    "./nest": "./dist/nest.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@grpc/grpc-js": "^1.12.4",
+    "@magield/proto": "0.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "@magield/gateway": "0.6.1",
+    "@magield/storage": "0.6.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.