@inkbox/sdk 0.1.4 → 0.2.1

package/dist/vault/totp.js

@@ -0,0 +1,230 @@
+/**
+ * inkbox-vault/totp.ts
+ *
+ * Client-side TOTP (RFC 6238) implementation.
+ */
+import { createHmac } from "node:crypto";
+// ---- Enums ----
+/**
+ * Hash algorithm for TOTP code generation.
+ *
+ * Values are lowercase to match `otpauth://` URI convention.
+ */
+export const TOTPAlgorithm = {
+    SHA1: "sha1",
+    SHA256: "sha256",
+    SHA512: "sha512",
+};
+// ---- Validation ----
+const VALID_ALGORITHMS = ["sha1", "sha256", "sha512"];
+const VALID_DIGITS = new Set([6, 8]);
+const VALID_PERIODS = new Set([30, 60]);
+/**
+ * Validate a TOTPConfig's fields.
+ *
+ * @throws Error if any field is invalid.
+ */
+export function validateTotpConfig(config) {
+    if (!config.secret || !config.secret.trim()) {
+        throw new Error("secret must be a non-empty base32 string");
+    }
+    b32decode(config.secret); // validate base32
+    const digits = config.digits ?? 6;
+    if (!VALID_DIGITS.has(digits)) {
+        throw new Error(`digits must be 6 or 8, got ${digits}`);
+    }
+    const period = config.period ?? 30;
+    if (!VALID_PERIODS.has(period)) {
+        throw new Error(`period must be 30 or 60, got ${period}`);
+    }
+    const alg = config.algorithm ?? "sha1";
+    if (!VALID_ALGORITHMS.includes(alg)) {
+        throw new Error(`algorithm must be sha1, sha256, or sha512, got ${alg}`);
+    }
+}
+// ---- Internal helpers ----
+/**
+ * Decode a base32 secret, adding padding if needed.
+ * @internal
+ */
+function b32decode(secret) {
+    const upper = secret.toUpperCase().replace(/=+$/, "");
+    if (upper.length === 0) {
+        throw new Error(`Invalid base32 secret: '${secret}'`);
+    }
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+    const bits = [];
+    for (const ch of upper) {
+        const idx = alphabet.indexOf(ch);
+        if (idx === -1)
+            throw new Error(`Invalid base32 secret: '${secret}'`);
+        for (let i = 4; i >= 0; i--) {
+            bits.push((idx >> i) & 1);
+        }
+    }
+    const bytes = [];
+    for (let i = 0; i + 8 <= bits.length; i += 8) {
+        let byte = 0;
+        for (let j = 0; j < 8; j++)
+            byte = (byte << 1) | bits[i + j];
+        bytes.push(byte);
+    }
+    if (bytes.length === 0) {
+        throw new Error(`Invalid base32 secret: '${secret}'`);
+    }
+    return Buffer.from(bytes);
+}
+/**
+ * Generate an HOTP code per RFC 4226 (internal helper).
+ * @internal
+ */
+function generateHotp(secret, counter, algorithm = "sha1", digits = 6) {
+    const key = b32decode(secret);
+    const msg = Buffer.alloc(8);
+    // Write counter as big-endian u64
+    msg.writeUInt32BE(Math.floor(counter / 0x100000000), 0);
+    msg.writeUInt32BE(counter >>> 0, 4);
+    const h = createHmac(algorithm, key).update(msg).digest();
+    const offset = h[h.length - 1] & 0x0f;
+    const code = ((h[offset] & 0x7f) << 24) |
+        ((h[offset + 1] & 0xff) << 16) |
+        ((h[offset + 2] & 0xff) << 8) |
+        (h[offset + 3] & 0xff);
+    return String(code % 10 ** digits).padStart(digits, "0");
+}
+// ---- Public API ----
+/**
+ * Generate the current TOTP code per RFC 6238.
+ *
+ * @param config - TOTP configuration with the shared secret and parameters.
+ * @returns A {@link TOTPCode} with the code and timing metadata.
+ */
+export function generateTotp(config) {
+    validateTotpConfig(config);
+    const algorithm = config.algorithm ?? "sha1";
+    const digits = config.digits ?? 6;
+    const period = config.period ?? 30;
+    const now = Math.floor(Date.now() / 1000);
+    const counter = Math.floor(now / period);
+    const periodStart = counter * period;
+    const periodEnd = periodStart + period;
+    const secondsRemaining = periodEnd - now;
+    const code = generateHotp(config.secret, counter, algorithm, digits);
+    return { code, periodStart, periodEnd, secondsRemaining };
+}
+/**
+ * Parse an `otpauth://totp/...` URI into a {@link TOTPConfig}.
+ *
+ * Supports the Google Authenticator Key URI format.
+ * Rejects HOTP URIs with an error.
+ *
+ * @param uri - The full `otpauth://` URI string.
+ * @returns A validated {@link TOTPConfig}.
+ * @throws Error on invalid scheme, HOTP type, missing secret, or invalid parameters.
+ */
+export function parseTotpUri(uri) {
+    let parsed;
+    try {
+        parsed = new URL(uri);
+    }
+    catch {
+        throw new Error(`Invalid URI: ${uri}`);
+    }
+    if (parsed.protocol !== "otpauth:") {
+        throw new Error(`Invalid scheme: expected 'otpauth', got '${parsed.protocol.replace(":", "")}'`);
+    }
+    const otpType = parsed.hostname;
+    if (otpType === "hotp") {
+        throw new Error("HOTP is not supported — only TOTP URIs are accepted");
+    }
+    if (otpType !== "totp") {
+        throw new Error(`Invalid OTP type: expected 'totp', got '${otpType}'`);
+    }
+    // Parse label — path is /<label>, label is [Issuer:]AccountName
+    const label = decodeURIComponent(parsed.pathname.replace(/^\//, ""));
+    let labelIssuer;
+    let accountName;
+    if (label.includes(":")) {
+        const [issuerPart, ...rest] = label.split(":");
+        labelIssuer = issuerPart.trim();
+        accountName = rest.join(":").trim();
+    }
+    else {
+        accountName = label.trim() || undefined;
+    }
+    // Secret (required)
+    const secret = parsed.searchParams.get("secret");
+    if (!secret) {
+        throw new Error("Missing required 'secret' parameter");
+    }
+    const secretUpper = secret.toUpperCase();
+    b32decode(secretUpper); // validate
+    // Issuer — query param takes precedence over label prefix
+    const issuer = parsed.searchParams.get("issuer") || labelIssuer || undefined;
+    // Algorithm
+    const algorithmStr = (parsed.searchParams.get("algorithm") || "sha1").toLowerCase();
+    if (!VALID_ALGORITHMS.includes(algorithmStr)) {
+        throw new Error(`Invalid algorithm: '${algorithmStr}'. Must be one of: sha1, sha256, sha512`);
+    }
+    const algorithm = algorithmStr;
+    // Digits
+    const digitsStr = parsed.searchParams.get("digits") || "6";
+    if (!/^\d+$/.test(digitsStr)) {
+        throw new Error(`Invalid digits: '${digitsStr}'. Must be 6 or 8`);
+    }
+    const digits = Number(digitsStr);
+    if (!VALID_DIGITS.has(digits)) {
+        throw new Error(`Invalid digits: '${digitsStr}'. Must be 6 or 8`);
+    }
+    // Period
+    const periodStr = parsed.searchParams.get("period") || "30";
+    if (!/^\d+$/.test(periodStr)) {
+        throw new Error(`Invalid period: '${periodStr}'. Must be 30 or 60`);
+    }
+    const period = Number(periodStr);
+    if (!VALID_PERIODS.has(period)) {
+        throw new Error(`Invalid period: '${periodStr}'. Must be 30 or 60`);
+    }
+    const config = {
+        secret: secretUpper,
+        algorithm,
+        digits,
+        period,
+        issuer,
+        accountName: accountName || undefined,
+    };
+    validateTotpConfig(config);
+    return config;
+}
+// ---- Serialization helpers for wire format (camelCase ↔ snake_case) ----
+/** Serialize a TOTPConfig to the snake_case wire format. @internal */
+export function serializeTotpConfig(config) {
+    const d = {
+        secret: config.secret,
+    };
+    if (config.algorithm !== undefined)
+        d.algorithm = config.algorithm;
+    if (config.digits !== undefined)
+        d.digits = config.digits;
+    if (config.period !== undefined)
+        d.period = config.period;
+    if (config.issuer !== undefined)
+        d.issuer = config.issuer;
+    if (config.accountName !== undefined)
+        d.account_name = config.accountName;
+    return d;
+}
+/** Parse a TOTPConfig from the snake_case wire format. @internal */
+export function parseTotpConfig(raw) {
+    const config = {
+        secret: raw.secret,
+        algorithm: raw.algorithm ?? "sha1",
+        digits: raw.digits ?? 6,
+        period: raw.period ?? 30,
+        issuer: raw.issuer,
+        accountName: raw.account_name ?? undefined,
+    };
+    validateTotpConfig(config);
+    return config;
+}
+//# sourceMappingURL=totp.js.map

package/dist/vault/totp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.js","sourceRoot":"","sources":["../../src/vault/totp.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,kBAAkB;AAElB;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;CACR,CAAC;AAmCX,uBAAuB;AAEvB,MAAM,gBAAgB,GAAsB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACzE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACrC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAkB;IACnD,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,kBAAkB;IAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,gCAAgC,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC;IACvC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,kDAAkD,GAAG,EAAE,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC;AAED,6BAA6B;AAE7B;;;GAGG;AACH,SAAS,SAAS,CAAC,MAAc;IAC/B,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,GAAG,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,QAAQ,GAAG,kCAAkC,CAAC;IACpD,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACjC,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,GAAG,CAAC,CAAC;QACtE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YAAE,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7D,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,GAAG,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CACnB,MAAc,EACd,OAAe,EACf,YAA2B,MAAM,EACjC,SAAiB,CAAC;IAElB,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC5B,kCAAkC;IAClC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;IACxD,GAAG,CAAC,aAAa,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAEpC,MAAM,CAAC,GAAG,UAAU,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1D,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;IACtC,MAAM,IAAI,GACR,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9B,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEzB,OAAO,MAAM,CAAC,IAAI,GAAG,EAAE,IAAI,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED,uBAAuB;AAEvB;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAkB;IAC7C,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAE3B,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;IAEnC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;IACrC,MAAM,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;IACvC,MAAM,gBAAgB,GAAG,SAAS,GAAG,GAAG,CAAC;IAEzC,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAErE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,4CAA4C,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAChF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC;IAChC,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,2CAA2C,OAAO,GAAG,CAAC,CAAC;IACzE,CAAC;IAED,gEAAgE;IAChE,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACrE,IAAI,WAA+B,CAAC;IACpC,IAAI,WAA+B,CAAC;IACpC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/C,WAAW,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;QAChC,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,WAAW,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;IAC1C,CAAC;IAED,oBAAoB;IACpB,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACzC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW;IAEnC,0DAA0D;IAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,WAAW,IAAI,SAAS,CAAC;IAE7E,YAAY;IACZ,MAAM,YAAY,GAAG,CACnB,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,MAAM,CAC/C,CAAC,WAAW,EAAE,CAAC;IAChB,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,uBAAuB,YAAY,yCAAyC,CAC7E,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,YAA6B,CAAC;IAEhD,SAAS;IACT,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC;IAC3D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,oBAAoB,SAAS,mBAAmB,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IACjC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,oBAAoB,SAAS,mBAAmB,CAAC,CAAC;IACpE,CAAC;IAED,SAAS;IACT,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC;IAC5D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,oBAAoB,SAAS,qBAAqB,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IACjC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,oBAAoB,SAAS,qBAAqB,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,MAAM,GAAe;QACzB,MAAM,EAAE,WAAW;QACnB,SAAS;QACT,MAAM;QACN,MAAM;QACN,MAAM;QACN,WAAW,EAAE,WAAW,IAAI,SAAS;KACtC,CAAC;IACF,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,2EAA2E;AAE3E,sEAAsE;AACtE,MAAM,UAAU,mBAAmB,CACjC,MAAkB;IAElB,MAAM,CAAC,GAA4B;QACjC,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC;IACF,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;QAAE,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACnE,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1D,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1D,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1D,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS;QAAE,CAAC,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC;IAC1E,OAAO,CAAC,CAAC;AACX,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,eAAe,CAC7B,GAA4B;IAE5B,MAAM,MAAM,GAAe;QACzB,MAAM,EAAE,GAAG,CAAC,MAAgB;QAC5B,SAAS,EAAG,GAAG,CAAC,SAA2B,IAAI,MAAM;QACrD,MAAM,EAAG,GAAG,CAAC,MAAiB,IAAI,CAAC;QACnC,MAAM,EAAG,GAAG,CAAC,MAAiB,IAAI,EAAE;QACpC,MAAM,EAAE,GAAG,CAAC,MAA4B;QACxC,WAAW,EAAG,GAAG,CAAC,YAAuB,IAAI,SAAS;KACvD,CAAC;IACF,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/vault/types.d.ts

@@ -0,0 +1,239 @@
+/**
+ * inkbox-vault TypeScript SDK — public types.
+ *
+ * Includes API response types, raw JSON shapes, parsers,
+ * and client-side structured secret payloads.
+ */
+import type { TOTPConfig } from "./totp.js";
+/**
+ * Category of credential stored in a vault secret.
+ *
+ * Used as a client-side hint for which form to render. The server
+ * does not validate or enforce payload structure (it's opaque ciphertext).
+ */
+export declare const VaultSecretType: {
+    readonly API_KEY: "api_key";
+    readonly KEY_PAIR: "key_pair";
+    readonly LOGIN: "login";
+    readonly SSH_KEY: "ssh_key";
+    readonly OTHER: "other";
+};
+export type VaultSecretType = (typeof VaultSecretType)[keyof typeof VaultSecretType];
+/**
+ * Discriminator for vault key records.
+ *
+ * - `PRIMARY` — a standard vault key issued to users or agents.
+ * - `RECOVERY` — a recovery code generated at vault initialization.
+ */
+export declare const VaultKeyType: {
+    readonly PRIMARY: "primary";
+    readonly RECOVERY: "recovery";
+};
+export type VaultKeyType = (typeof VaultKeyType)[keyof typeof VaultKeyType];
+/** Vault metadata returned by the info endpoint. */
+export interface VaultInfo {
+    id: string;
+    organizationId: string;
+    /** @example "active" */
+    status: string;
+    createdAt: Date;
+    updatedAt: Date;
+    /** Number of active primary vault keys. */
+    keyCount: number;
+    /** Number of active vault secrets. */
+    secretCount: number;
+    /** Number of active recovery keys. */
+    recoveryKeyCount: number;
+}
+/** Vault key metadata (no wrapped key material). */
+export interface VaultKey {
+    id: string;
+    /** `"primary"` or `"recovery"` */
+    keyType: string;
+    /** Clerk user ID of the creator, or `null`. */
+    createdBy: string | null;
+    status: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Vault secret metadata (no encrypted payload). */
+export interface VaultSecret {
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Optional description. */
+    description: string | null;
+    /** `"login"` | `"ssh_key"` | `"api_key"` | `"other"` */
+    secretType: string;
+    status: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Vault secret including the encrypted payload. */
+export interface VaultSecretDetail extends VaultSecret {
+    /** Base64-encoded AES-256-GCM ciphertext. */
+    encryptedPayload: string;
+}
+/** A rule granting an identity access to a vault secret. */
+export interface AccessRule {
+    id: string;
+    vaultSecretId: string;
+    identityId: string;
+    createdAt: Date;
+}
+/** @internal */
+export interface RawAccessRule {
+    id: string;
+    vault_secret_id: string;
+    identity_id: string;
+    created_at: string;
+}
+/** @internal */
+export declare function parseAccessRule(r: RawAccessRule): AccessRule;
+/** Payload for `login` secrets. At least one of `username` or `email` should be provided. */
+export interface LoginPayload {
+    password: string;
+    username?: string;
+    email?: string;
+    /** URL of the service. */
+    url?: string;
+    notes?: string;
+    /** Optional TOTP configuration for two-factor authentication. */
+    totp?: TOTPConfig;
+}
+/** Payload for `other` (freeform catch-all) secrets. */
+export interface OtherPayload {
+    /** Freeform content. */
+    data: string;
+    notes?: string;
+}
+/** Payload for `ssh_key` secrets. */
+export interface SSHKeyPayload {
+    /** SSH private key (PEM or OpenSSH format). */
+    privateKey: string;
+    publicKey?: string;
+    fingerprint?: string;
+    /** Passphrase protecting the private key, if any. */
+    passphrase?: string;
+    notes?: string;
+}
+/** Payload for `api_key` secrets (single token). */
+export interface APIKeyPayload {
+    /** The API key or token. */
+    apiKey: string;
+    /** API endpoint URL. */
+    endpoint?: string;
+    notes?: string;
+}
+/** Payload for `key_pair` secrets (access key + secret key). */
+export interface KeyPairPayload {
+    /** The access key identifier. */
+    accessKey: string;
+    /** The secret key. */
+    secretKey: string;
+    /** API endpoint URL. */
+    endpoint?: string;
+    notes?: string;
+}
+/** Union of all secret payload types. */
+export type SecretPayload = LoginPayload | OtherPayload | SSHKeyPayload | APIKeyPayload | KeyPairPayload;
+/** A vault secret with its payload decrypted into a structured type. */
+export interface DecryptedVaultSecret {
+    id: string;
+    /** Display name. */
+    name: string;
+    description: string | null;
+    /** `"login"` | `"ssh_key"` | `"api_key"` | `"other"` */
+    secretType: string;
+    status: string;
+    createdAt: Date;
+    updatedAt: Date;
+    /** The decrypted, structured payload. */
+    payload: SecretPayload;
+}
+/** @internal */
+export interface RawVaultInfo {
+    id: string;
+    organization_id: string;
+    status: string;
+    created_at: string;
+    updated_at: string;
+    key_count: number;
+    secret_count: number;
+    recovery_key_count: number;
+}
+/** @internal */
+export interface RawVaultKey {
+    id: string;
+    key_type: string;
+    created_by: string | null;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+/** @internal */
+export interface RawVaultSecret {
+    id: string;
+    name: string;
+    description: string | null;
+    secret_type: string;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+/** @internal */
+export interface RawVaultSecretDetail extends RawVaultSecret {
+    encrypted_payload: string;
+}
+/** @internal */
+export interface RawVaultUnlockResponse {
+    wrapped_org_encryption_key: string | null;
+    wrapped_org_encryption_keys: Array<{
+        id: string;
+        auth_hash: string;
+        wrapped_org_encryption_key: string;
+    }> | null;
+    encrypted_secrets: RawVaultSecretDetail[];
+}
+/** Parse a raw vault info response into a {@link VaultInfo}. @internal */
+export declare function parseVaultInfo(r: RawVaultInfo): VaultInfo;
+/** Parse a raw vault key response into a {@link VaultKey}. @internal */
+export declare function parseVaultKey(r: RawVaultKey): VaultKey;
+/** Parse a raw vault secret response into a {@link VaultSecret}. @internal */
+export declare function parseVaultSecret(r: RawVaultSecret): VaultSecret;
+/** Parse a raw vault secret detail response into a {@link VaultSecretDetail}. @internal */
+export declare function parseVaultSecretDetail(r: RawVaultSecretDetail): VaultSecretDetail;
+/**
+ * Serialize a payload into a plain object for encryption.
+ *
+ * Converts camelCase payload fields to the snake_case wire format
+ * stored inside the encrypted blob.
+ *
+ * @param secretType - The secret type string.
+ * @param payload - The structured payload to serialize.
+ * @returns A plain object ready for JSON stringification.
+ * @throws If `secretType` is unknown.
+ * @internal
+ */
+export declare function serializePayload(secretType: string, payload: SecretPayload): Record<string, unknown>;
+/**
+ * Parse a decrypted plain object into the correct payload type.
+ *
+ * Converts snake_case wire-format fields back to camelCase.
+ *
+ * @param secretType - The secret type string.
+ * @param raw - The decrypted plain object.
+ * @returns The typed payload.
+ * @throws If `secretType` is unknown.
+ * @internal
+ */
+export declare function parsePayload(secretType: string, raw: Record<string, unknown>): SecretPayload;
+/**
+ * Infer the `secretType` string from a payload's shape.
+ *
+ * @param payload - A secret payload object.
+ * @returns The inferred secret type string.
+ * @throws If the payload shape doesn't match any known type.
+ */
+export declare function inferSecretType(payload: SecretPayload): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/vault/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/vault/types.ts"],"names":[],"mappings":"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"}