@hawcx/protocol 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Hawcx Auth Protocol v1 Type Definitions
+ *
+ * This file is the source of truth for TYPE SHAPES (request/response structures).
+ * Generate Swift/Kotlin/Dart types from this file.
+ *
+ * For behavioral rules, see protocol-v1-spec.md:
+ * - Required HTTP headers (X-Hawcx-SDK, X-Tenant-Id, etc.)
+ * - Unknown prompt handling (graceful fallback)
+ * - Session lifecycle (empty string on version mismatch)
+ * - Rate limiting and retry semantics
+ *
+ * @version 1.0.0
+ */
+export declare const PROTOCOL_VERSION: 1;
+export interface AuthRequest {
+    protocolVersion: typeof PROTOCOL_VERSION;
+    session?: string;
+    action: Action;
+}
+export interface AuthResponse {
+    protocolVersion: typeof PROTOCOL_VERSION;
+    session: string;
+    prompt: Prompt;
+    meta: ResponseMeta;
+}
+export interface ResponseMeta {
+    /** Unique request identifier for tracing */
+    traceId: string;
+    /** Session expiration (ISO 8601) */
+    expiresAt: string;
+}
+export type Action = ActionStart | ActionSelectMethod | ActionSubmitCode | ActionSubmitTotp | ActionSubmitPhone | ActionRequestChallenge | ActionSubmitSignature | ActionOAuthCallback | ActionResend | ActionPoll | ActionCancel;
+export interface ActionStart {
+    type: "start";
+    /** Server-defined flow type (e.g., "signin", "signup", "account_manage") */
+    flowType: string;
+    identifier: string;
+    /** Required for some flows (e.g., step-up auth) */
+    startToken?: string;
+    /** Optional device fingerprinting data */
+    device?: DeviceInfo;
+    /** Device credentials for automatic device trust verification (SDK sends if available) */
+    deviceCredentials?: DeviceCredentials;
+}
+/**
+ * Stored device credentials for device trust verification at flow start.
+ * SDK loads these from IndexedDB and sends them automatically for signin flows.
+ */
+export interface DeviceCredentials {
+    /** Base64-encoded encrypted keyset containing public/private key pair */
+    keyset: string;
+    /** Base64-encoded hash index for device lookup */
+    hindex: string;
+    /** Base64-encoded secret key used to decrypt keyset */
+    sk2: string;
+}
+export interface DeviceInfo {
+    /** Schema version for handling different DeviceInfo formats from different SDK versions */
+    v: 1;
+    /** SDK-computed fingerprint hash - the primary device identifier */
+    fingerprint: string;
+    /** All other device data (userAgent, os, timezone, screen, locale, etc.) */
+    signals?: Record<string, unknown>;
+}
+export interface ActionSelectMethod {
+    type: "select_method";
+    methodId: string;
+}
+export interface ActionSubmitCode {
+    type: "submit_code";
+    code: string;
+}
+export interface ActionSubmitTotp {
+    type: "submit_totp";
+    /** 6-8 digit TOTP code */
+    code: string;
+}
+export interface ActionSubmitPhone {
+    type: "submit_phone";
+    /** Phone number in E.164 format (e.g., "+1234567890") */
+    phone: string;
+}
+/**
+ * Request a device challenge from the server.
+ *
+ * SDK-INTERNAL: Used during device enrollment to send the generated keyset
+ * to the server and receive a challenge to sign. This action is sent
+ * automatically by the SDK after receiving a setup_device prompt.
+ */
+export interface ActionRequestChallenge {
+    type: "request_challenge";
+    /** Base64-encoded encrypted keyset containing the public key */
+    keyset: string;
+    /** Base64-encoded hash index for key lookup */
+    hindex: string;
+    /** Base64-encoded SK2 for keyset decryption */
+    sk2: string;
+}
+export interface ActionSubmitSignature {
+    type: "submit_signature";
+    keyId: string;
+    signature: string;
+    mapp: string;
+}
+export interface ActionOAuthCallback {
+    type: "oauth_callback";
+    code: string;
+    state: string;
+}
+export interface ActionResend {
+    type: "resend";
+}
+export interface ActionPoll {
+    type: "poll";
+}
+export interface ActionCancel {
+    type: "cancel";
+}
+export type Prompt = PromptSelectMethod | PromptEnterCode | PromptEnterTotp | PromptSetupTotp | PromptSetupSms | PromptSetupDevice | PromptDeviceChallenge | PromptRedirect | PromptAwaitApproval | PromptCompleted | PromptError;
+export interface PromptSelectMethod {
+    type: "select_method";
+    /** Current phase: "primary", "mfa", or "enrollment" */
+    phase: "primary" | "mfa" | "enrollment";
+    methods: Method[];
+}
+export interface PromptEnterCode {
+    type: "enter_code";
+    /** Masked destination. Example: "s***@example.com" */
+    destination: string;
+    /** Expected code length */
+    codeLength: number;
+    /** Code format for keyboard hints */
+    codeFormat: "numeric" | "alphanumeric";
+    /** When code expires (ISO 8601) */
+    codeExpiresAt: string;
+    /** When resend is available (ISO 8601) */
+    resendAt: string;
+}
+export interface PromptEnterTotp {
+    type: "enter_totp";
+}
+export interface PromptSetupTotp {
+    type: "setup_totp";
+    /** Base32-encoded TOTP secret */
+    secret: string;
+    /** otpauth:// URL for QR code generation */
+    otpauthUrl: string;
+    /** TOTP period in seconds (typically 30) */
+    period: number;
+}
+/**
+ * SMS enrollment prompt.
+ *
+ * Shown when user needs to provide a phone number for SMS OTP.
+ * Client should display phone input field.
+ */
+export interface PromptSetupSms {
+    type: "setup_sms";
+    /** Optional: existing masked phone to replace */
+    existingPhone?: string;
+}
+/**
+ * Device enrollment prompt.
+ *
+ * SDK-INTERNAL: This prompt is handled automatically by SDKs and MUST NOT be
+ * rendered to users. When received, SDKs should:
+ * 1. Generate an Ed25519 keypair
+ * 2. Store the keypair securely (IndexedDB/Keychain)
+ * 3. Build the encrypted keyset with hindex
+ * 4. Send a request_challenge action with the keyset
+ *
+ * This prompt is returned during the enrollment phase when no device key
+ * exists yet (signup or first signin on new device).
+ */
+export interface PromptSetupDevice {
+    type: "setup_device";
+    /** Domain for key binding */
+    domain: string;
+    /** Algorithm for key generation */
+    algorithm: "Ed25519";
+    /** Version of the enrollment protocol */
+    version: string;
+}
+/**
+ * Device verification challenge.
+ *
+ * SDK-INTERNAL: This prompt is handled automatically by SDKs and MUST NOT be
+ * rendered to users. SDKs intercept this prompt, load the private key from
+ * secure storage, sign the challenge, and submit automatically.
+ *
+ * This prompt may be returned immediately after `start` when device trust is
+ * enabled and the device is recognized.
+ */
+export interface PromptDeviceChallenge {
+    type: "device_challenge";
+    /** Challenge bytes to sign */
+    challenge: string;
+    /** Encoding of challenge */
+    challengeEncoding: "base64";
+    /** Key ID to use for signing */
+    keyId: string;
+    /** Signature algorithm */
+    algorithm: "Ed25519";
+    /** Domain for signature binding */
+    domain: string;
+    /** Base64-encoded combinedsalt for key unwrap */
+    combinedsalt: string;
+    /** Expected response encoding */
+    responseEncoding: "base64";
+}
+export interface PromptRedirect {
+    type: "redirect";
+    /** Full redirect URL */
+    url: string;
+    /** Deep link scheme for mobile */
+    returnScheme?: string;
+}
+export interface PromptAwaitApproval {
+    type: "await_approval";
+    /** QR code data (optional) */
+    qrData?: string;
+    /** When approval expires (ISO 8601) */
+    expiresAt: string;
+    /** Suggested poll interval in seconds */
+    pollInterval: number;
+}
+export interface PromptCompleted {
+    type: "completed";
+    /** Authorization code */
+    authCode: string;
+    /** When auth code expires (ISO 8601) */
+    expiresAt: string;
+}
+/**
+ * Server-driven error actions.
+ *
+ * These tell the client what to do. Keep this set small and stable.
+ * Unknown actions from newer servers should fall back to showing the message.
+ */
+export type ErrorAction = "retry_input" | "restart_flow" | "wait" | "retry_request" | "abort" | "resend_code" | "select_method";
+/**
+ * Error prompt with server-driven action.
+ *
+ * @example
+ * ```typescript
+ * if (isPromptError(prompt)) {
+ *   switch (prompt.action) {
+ *     case "retry_input":
+ *       showError(prompt.message);
+ *       focusInput();
+ *       break;
+ *     case "wait":
+ *       await delay(prompt.details.retry_after_seconds * 1000);
+ *       retry();
+ *       break;
+ *     case "restart_flow":
+ *       client.reset();
+ *       navigate("/auth");
+ *       break;
+ *     default:
+ *       // Unknown action from newer server
+ *       showError(prompt.message);
+ *   }
+ * }
+ * ```
+ */
+export interface PromptError {
+    type: "error";
+    /** Machine-readable error code (for logging, not branching) */
+    code: string;
+    /** Server-driven action - BRANCH ON THIS */
+    action: ErrorAction | (string & {});
+    /** Human-readable message */
+    message: string;
+    /** Whether user can retry */
+    retryable: boolean;
+    /** Additional error details (varies by action) */
+    details?: ErrorDetails;
+}
+/**
+ * Error details - varies by action.
+ *
+ * - `wait` action requires `retry_after_seconds`
+ * - Other actions may have additional context
+ */
+export interface ErrorDetails {
+    /** Seconds to wait before retry (for "wait" action) */
+    retry_after_seconds?: number;
+    /** Validation errors (for validation failures) */
+    errors?: Array<{
+        field: string;
+        message: string;
+    }>;
+    /** Any additional context */
+    [key: string]: unknown;
+}
+export interface Method {
+    /** Unique method identifier */
+    id: string;
+    /** Human-readable label */
+    label: string;
+    /** Icon identifier (optional) */
+    icon?: string;
+}
+export declare function isPromptSelectMethod(p: Prompt): p is PromptSelectMethod;
+export declare function isPromptEnterCode(p: Prompt): p is PromptEnterCode;
+export declare function isPromptEnterTotp(p: Prompt): p is PromptEnterTotp;
+export declare function isPromptSetupTotp(p: Prompt): p is PromptSetupTotp;
+export declare function isPromptSetupSms(p: Prompt): p is PromptSetupSms;
+export declare function isPromptSetupDevice(p: Prompt): p is PromptSetupDevice;
+export declare function isPromptDeviceChallenge(p: Prompt): p is PromptDeviceChallenge;
+export declare function isPromptRedirect(p: Prompt): p is PromptRedirect;
+export declare function isPromptAwaitApproval(p: Prompt): p is PromptAwaitApproval;
+export declare function isPromptCompleted(p: Prompt): p is PromptCompleted;
+export declare function isPromptError(p: Prompt): p is PromptError;
+/** Extract action type for type narrowing */
+export type ActionType = Action["type"];
+/** Extract prompt type for type narrowing */
+export type PromptType = Prompt["type"];
+/** Get prompt by type */
+export type PromptByType<T extends PromptType> = Extract<Prompt, {
+    type: T;
+}>;
+/** Get action by type */
+export type ActionByType<T extends ActionType> = Extract<Action, {
+    type: T;
+}>;

package/dist/index.js

@@ -0,0 +1,54 @@
+/**
+ * Hawcx Auth Protocol v1 Type Definitions
+ *
+ * This file is the source of truth for TYPE SHAPES (request/response structures).
+ * Generate Swift/Kotlin/Dart types from this file.
+ *
+ * For behavioral rules, see protocol-v1-spec.md:
+ * - Required HTTP headers (X-Hawcx-SDK, X-Tenant-Id, etc.)
+ * - Unknown prompt handling (graceful fallback)
+ * - Session lifecycle (empty string on version mismatch)
+ * - Rate limiting and retry semantics
+ *
+ * @version 1.0.0
+ */
+// ============================================================================
+// Protocol Version
+// ============================================================================
+export const PROTOCOL_VERSION = 1;
+// ============================================================================
+// Type Guards
+// ============================================================================
+export function isPromptSelectMethod(p) {
+    return p.type === "select_method";
+}
+export function isPromptEnterCode(p) {
+    return p.type === "enter_code";
+}
+export function isPromptEnterTotp(p) {
+    return p.type === "enter_totp";
+}
+export function isPromptSetupTotp(p) {
+    return p.type === "setup_totp";
+}
+export function isPromptSetupSms(p) {
+    return p.type === "setup_sms";
+}
+export function isPromptSetupDevice(p) {
+    return p.type === "setup_device";
+}
+export function isPromptDeviceChallenge(p) {
+    return p.type === "device_challenge";
+}
+export function isPromptRedirect(p) {
+    return p.type === "redirect";
+}
+export function isPromptAwaitApproval(p) {
+    return p.type === "await_approval";
+}
+export function isPromptCompleted(p) {
+    return p.type === "completed";
+}
+export function isPromptError(p) {
+    return p.type === "error";
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hawcx/protocol",
+  "version": "1.0.0",
+  "description": "Canonical protocol types and helpers for the Hawcx auth flow.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "node ./node_modules/typescript/bin/tsc -p tsconfig.build.json",
+    "test": "node ./node_modules/vitest/vitest.mjs run"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  }
+}