secryn 1.0.0

package/dist/src/client.js

@@ -0,0 +1,363 @@
+import { logger } from "./logger.js";
+export class SecrynApiError extends Error {
+    statusCode;
+    code;
+    details;
+    /**
+     * @param message     - Human-readable error description from the API.
+     * @param statusCode  - HTTP status code returned by the server.
+     * @param code        - Machine-readable error identifier (e.g. ``"NOT_FOUND"``).
+     * @param details     - Optional structured context (validation errors, etc.).
+     */
+    constructor(message, statusCode, code, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.details = details;
+        this.name = "SecrynApiError";
+    }
+}
+/**
+ * Normalise a base URL and a relative path into a single absolute URL.
+ *
+ * Strips a trailing ``/`` from the base and ensures the path starts with
+ * ``/`` so that the resulting URL has exactly one separator between host
+ * and path regardless of the caller's formatting.
+ *
+ * @param base - Base URL with optional trailing slash.
+ * @param path - Relative API path with optional leading slash.
+ * @returns Fully-qualified URL string.
+ */
+function buildUrl(base, path) {
+    const normalizedBase = base.endsWith("/") ? base.slice(0, -1) : base;
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    return `${normalizedBase}${normalizedPath}`;
+}
+// ---------------------------------------------------------------------------
+// Cookie jar — persists auth tokens across requests in Node.js.
+//
+// Node's native ``fetch`` does not automatically store or send cookies the
+// way browsers do. This class manually parses ``Set-Cookie`` response headers
+// and injects a ``Cookie`` header on subsequent requests so that cookie-based
+// authentication works server-side.
+// ---------------------------------------------------------------------------
+class CookieJar {
+    cookies = new Map();
+    /**
+     * Extract a cookie name/value pair from a ``Set-Cookie`` header value.
+     * Only the first ``name=value`` segment is kept; attributes (``Path``,
+     * ``HttpOnly``, etc.) are ignored.
+     */
+    setFromHeader(setCookieHeader) {
+        const parts = setCookieHeader.split(";");
+        const first = parts[0]?.trim();
+        if (!first)
+            return;
+        const eq = first.indexOf("=");
+        if (eq === -1)
+            return;
+        const name = first.slice(0, eq).trim();
+        const value = first.slice(eq + 1).trim();
+        if (value) {
+            this.cookies.set(name, value);
+        }
+    }
+    /**
+     * Serialise all stored cookies into a single ``Cookie`` header value.
+     * Returns an empty string when no cookies are stored.
+     */
+    getCookieHeader() {
+        if (this.cookies.size === 0)
+            return "";
+        return Array.from(this.cookies.entries())
+            .map(([n, v]) => `${n}=${v}`)
+            .join("; ");
+    }
+    clear() {
+        this.cookies.clear();
+    }
+}
+// ---------------------------------------------------------------------------
+// SecrynClient — HTTP client for the full Secryn REST API.
+//
+// Supports two authentication modes:
+//   • Cookie-based  — after ``auth.login``, session cookies are persisted
+//     across requests via an internal ``CookieJar``.
+//   • API-key-based — pass ``apiKey`` in the constructor options.
+//
+// All API resources are exposed as namespaced sub-objects (``auth``,
+// ``projects``, ``secrets``, etc.) for discoverable auto-completion.
+// ---------------------------------------------------------------------------
+export class SecrynClient {
+    baseUrl;
+    apiKey;
+    cookieJar = new CookieJar();
+    /**
+     * @param options - Optional configuration.
+     * @param options.baseUrl - Base URL including the ``/api/v1`` prefix.
+     *   Defaults to ``http://localhost:3000/api/v1``.
+     * @param options.apiKey - Optional API key for programmatic access.
+     */
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl ?? "http://localhost:3000/api/v1";
+        this.apiKey = options.apiKey;
+    }
+    // ---- raw HTTP -----------------------------------------------------------
+    /**
+     * Execute an HTTP request and handle common response semantics.
+     *
+     * Key behaviours:
+     * - Injects stored cookies from the internal cookie jar as the
+     *   ``Cookie`` header (enabling session-based auth).
+     * - Injects the ``api-key`` header when the client was configured with one.
+     * - Persists ``Set-Cookie`` response headers back into the cookie jar.
+     * - Returns ``undefined`` for 204 No Content responses.
+     * - Parses the body as JSON; falls back to returning the raw text on
+     *   parse failure.
+     * - Throws {@link SecrynApiError} when ``response.ok`` is ``false``,
+     *   extracting ``message``, ``code``, and ``details`` from the JSON body
+     *   when available.
+     *
+     * @param opts - Request definition.
+     * @template T - Expected shape of the parsed JSON response.
+     * @returns Parsed JSON typed as ``T``, or ``undefined`` for 204.
+     * @throws {SecrynApiError} When the API responds with a non-2xx status.
+     */
+    async request(opts) {
+        const url = buildUrl(this.baseUrl, opts.path);
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+        const cookieHeader = this.cookieJar.getCookieHeader();
+        if (cookieHeader) {
+            headers["Cookie"] = cookieHeader;
+        }
+        if (this.apiKey) {
+            headers["api-key"] = this.apiKey;
+        }
+        const init = {
+            method: opts.method,
+            headers,
+        };
+        if (opts.body !== undefined) {
+            init.body = JSON.stringify(opts.body);
+        }
+        const response = await fetch(url, init);
+        // Persist cookies
+        const setCookie = response.headers.get("set-cookie");
+        if (setCookie) {
+            this.cookieJar.setFromHeader(setCookie);
+        }
+        // 204 No Content
+        if (response.status === 204) {
+            return undefined;
+        }
+        const text = await response.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = text;
+        }
+        if (!response.ok) {
+            const err = data;
+            throw new SecrynApiError(err?.message ?? `HTTP ${response.status}`, response.status, err?.code ?? "UNKNOWN", err?.details);
+        }
+        return data;
+    }
+    // ---- convenience shortcuts ----------------------------------------------
+    get(path) {
+        return this.request({ method: "GET", path });
+    }
+    post(path, body) {
+        return this.request({ method: "POST", path, body });
+    }
+    put(path, body) {
+        return this.request({ method: "PUT", path, body });
+    }
+    del(path) {
+        return this.request({ method: "DELETE", path });
+    }
+    // =====================================================================
+    // Auth
+    // =====================================================================
+    auth = {
+        login: async (email, password) => {
+            const body = { email, password };
+            const result = await this.post("/auth/login", body);
+            // Emit an audit log on every login attempt (success or failure is
+            // reflected by whether this call throws).
+            logger.audit("SDK_LOGIN", email);
+            return result;
+        },
+        register: async (email, password, username) => {
+            const body = { email, password, username };
+            return this.post("/auth/register", body);
+        },
+        /**
+         * Send a logout request and unconditionally clear the local cookie jar.
+         *
+         * The cookie jar is cleared inside a ``finally`` block so that even if
+         * the server returns an error the local session is still discarded.
+         */
+        logout: async () => {
+            try {
+                await this.post("/auth/logout");
+            }
+            finally {
+                this.cookieJar.clear();
+            }
+        },
+        refresh: async () => {
+            await this.post("/auth/refresh");
+        },
+        forgotPassword: async (email) => {
+            const body = { email };
+            return this.post("/auth/forgot-password", body);
+        },
+        resetPassword: async (token, password) => {
+            const body = { token, password };
+            return this.post("/auth/reset-password", body);
+        },
+        /**
+         * Check whether the client currently holds any session cookies.
+         * Does not validate the cookie with the server.
+         */
+        isAuthenticated: () => this.cookieJar.getCookieHeader() !== "",
+    };
+    // =====================================================================
+    // MFA
+    // =====================================================================
+    mfa = {
+        setup: () => this.get("/auth/mfa/setup"),
+        enable: (token) => {
+            const body = { token };
+            return this.post("/auth/mfa/enable", body);
+        },
+        disable: () => this.post("/auth/mfa/disable"),
+        confirm: (token, mfaToken) => {
+            const body = { token, mfaToken };
+            return this.post("/auth/mfa/confirm", body);
+        },
+        recovery: (code, mfaToken) => {
+            const body = { code, mfaToken };
+            return this.post("/auth/mfa/recovery", body);
+        },
+        recoveryCodes: () => this.get("/auth/mfa/recovery-codes"),
+        regenerateCodes: () => this.post("/auth/mfa/recovery-codes/regenerate"),
+        sendBackupCode: (email) => this.post("/auth/mfa/send-backup-code", { email }),
+        status: () => this.get("/auth/mfa/status"),
+    };
+    // =====================================================================
+    // Users
+    // =====================================================================
+    users = {
+        me: () => this.get("/users/@me"),
+        get: (userId) => this.get(`/users/${userId}`),
+        update: (data) => this.put("/users", data),
+        delete: () => this.del("/users"),
+    };
+    // =====================================================================
+    // API Keys
+    // =====================================================================
+    apiKeys = {
+        create: (name, permissions = ["read", "write"]) => {
+            const body = { name, permissions };
+            return this.post("/api-keys", body);
+        },
+        list: () => this.get("/api-keys/@all-user"),
+        get: (id) => this.get(`/api-keys/${id}`),
+        update: (id, data) => this.put(`/api-keys/${id}`, data),
+        delete: (id) => this.del(`/api-keys/${id}`),
+    };
+    // =====================================================================
+    // Projects
+    // =====================================================================
+    projects = {
+        create: (name, description) => {
+            const body = {
+                name,
+                description: description ?? "",
+            };
+            return this.post("/projects", body);
+        },
+        list: () => this.get("/projects/@all"),
+        get: (id) => this.get(`/projects/${id}`),
+        update: (id, data) => this.put(`/projects/${id}`, data),
+        delete: (id) => this.del(`/projects/${id}`),
+        transfer: (id, newOwnerId) => this.post(`/projects/${id}/transfer`, { newOwnerId }),
+    };
+    // =====================================================================
+    // Invites
+    // =====================================================================
+    invites = {
+        create: (projectId, email) => {
+            const body = {};
+            if (email)
+                body.email = email;
+            // Send body as-is (empty object when no email) so the server creates an
+            // open invite that any authenticated user can accept.
+            return this.post(`/projects/${projectId}/invites`, body);
+        },
+        /**
+         * Accept a project invitation by its unique slug.
+         *
+         * Uses ``GET`` instead of ``POST`` because the server identifies the
+         * invite via the URL slug and does not require a request body.
+         */
+        accept: (slug) => this.get(`/projects/invites/${slug}`),
+    };
+    // =====================================================================
+    // Members
+    // =====================================================================
+    members = {
+        remove: (projectId, memberId) => this.del(`/projects/${projectId}/members/${memberId}`),
+        addPermissions: (projectId, memberId, permissions) => this.post(`/projects/${projectId}/members/${memberId}/permissions`, { permissions }),
+        /**
+         * Remove permissions from a member.
+         *
+         * The ``.then()`` chain discards the API response body because the
+         * endpoint returns updated permissions on success but the caller only
+         * cares that the operation completed without error.
+         */
+        removePermissions: (projectId, memberId) => this.del(`/projects/${projectId}/members/${memberId}/permissions`).then(() => undefined),
+    };
+    // =====================================================================
+    // Secrets
+    // =====================================================================
+    secrets = {
+        create: (projectId, name, value, notes) => {
+            const body = {
+                name,
+                value,
+                notes: notes ?? "",
+            };
+            return this.post(`/projects/${projectId}/secrets`, body);
+        },
+        get: (id) => this.get(`/projects/secrets/${id}`),
+        list: (projectId) => this.get(`/projects/${projectId}/secrets`),
+        update: (id, data) => this.put(`/projects/secrets/${id}`, data),
+        delete: (id) => this.del(`/projects/secrets/${id}`),
+        /**
+         * Export all secrets of a project as a dotenv-formatted string.
+         *
+         * Uses raw ``fetch`` instead of the internal ``request`` helper because
+         * the endpoint returns ``text/plain``, not ``application/json``, and
+         * the response body must not be parsed as JSON.
+         *
+         * @throws {SecrynApiError} With code ``"EXPORT_ERROR"`` on non-2xx.
+         */
+        exportDotenv: (projectId) => fetch(buildUrl(this.baseUrl, `/projects/${projectId}/secrets/export`), {
+            headers: {
+                ...(this.cookieJar.getCookieHeader() ? { Cookie: this.cookieJar.getCookieHeader() } : {}),
+                ...(this.apiKey ? { "api-key": this.apiKey } : {}),
+            },
+        }).then((r) => {
+            if (!r.ok)
+                throw new SecrynApiError("Export failed", r.status, "EXPORT_ERROR");
+            return r.text();
+        }),
+    };
+}

package/dist/src/logger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Namespaced logger for the Secryn SDK.
+ *
+ * ``error`` and ``warn`` always write to the console.
+ * ``info``, ``debug``, and ``audit`` are gated behind the
+ * ``SECRYN_SDK_DEBUG`` environment variable (set to ``"1"`` to enable).
+ *
+ * All messages are prefixed with ``[secryn]`` for grep-friendly output.
+ */
+export declare const logger: {
+    error(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    info(message: string, meta?: unknown): void;
+    debug(message: string, meta?: unknown): void;
+    /**
+     * Emit a structured audit log entry.
+     *
+     * Format: ``[secryn] [AUDIT] <action> actor=<actor> resource=<resource>``.
+     * Gated behind ``SECRYN_SDK_DEBUG`` like ``info`` and ``debug``.
+     *
+     * @param action  - CRUD verb or custom action identifier (e.g. ``"login"``).
+     * @param actor   - Identifier of the principal (user ID, API key prefix).
+     * @param resource - Optional resource path or ID affected by the action.
+     * @param meta    - Optional unstructured context (serialized inline).
+     */
+    audit(action: string, actor: string, resource?: string, meta?: unknown): void;
+};

package/dist/src/logger.js

@@ -0,0 +1,43 @@
+/** Debug gate: set ``SECRYN_SDK_DEBUG=1`` to enable info/debug/audit output. */
+const isDebug = process.env["SECRYN_SDK_DEBUG"] === "1";
+/**
+ * Namespaced logger for the Secryn SDK.
+ *
+ * ``error`` and ``warn`` always write to the console.
+ * ``info``, ``debug``, and ``audit`` are gated behind the
+ * ``SECRYN_SDK_DEBUG`` environment variable (set to ``"1"`` to enable).
+ *
+ * All messages are prefixed with ``[secryn]`` for grep-friendly output.
+ */
+export const logger = {
+    error(message, meta) {
+        console.error(`[secryn] ERROR ${message}`, meta ?? "");
+    },
+    warn(message, meta) {
+        console.warn(`[secryn] WARN ${message}`, meta ?? "");
+    },
+    info(message, meta) {
+        if (isDebug)
+            console.info(`[secryn] INFO ${message}`, meta ?? "");
+    },
+    debug(message, meta) {
+        if (isDebug)
+            console.debug(`[secryn] DEBUG ${message}`, meta ?? "");
+    },
+    /**
+     * Emit a structured audit log entry.
+     *
+     * Format: ``[secryn] [AUDIT] <action> actor=<actor> resource=<resource>``.
+     * Gated behind ``SECRYN_SDK_DEBUG`` like ``info`` and ``debug``.
+     *
+     * @param action  - CRUD verb or custom action identifier (e.g. ``"login"``).
+     * @param actor   - Identifier of the principal (user ID, API key prefix).
+     * @param resource - Optional resource path or ID affected by the action.
+     * @param meta    - Optional unstructured context (serialized inline).
+     */
+    audit(action, actor, resource, meta) {
+        if (isDebug) {
+            console.info(`[secryn] [AUDIT] ${action} actor=${actor} resource=${resource ?? "-"}`, meta ?? "");
+        }
+    },
+};

package/dist/src/types.d.ts

@@ -0,0 +1,74 @@
+/** Request/response DTOs for the Secryn API — mirrored from @repo/shared. */
+export interface LoginBody {
+    email: string;
+    password: string;
+}
+export interface RegisterBody {
+    email: string;
+    password: string;
+    username?: string;
+}
+export interface LoginMFAResponse {
+    mfaRequired: true;
+    mfaToken: string;
+}
+export interface MFAConfirmBody {
+    token: string;
+    mfaToken: string;
+}
+export interface MFARecoveryBody {
+    code: string;
+    mfaToken: string;
+}
+export interface MFASetupResponse {
+    secret: string;
+    qrCode: string;
+    otpauthUrl: string;
+}
+export interface MFAEnableBody {
+    token: string;
+}
+export interface MFAStatusResponse {
+    enabled: boolean;
+}
+export interface MFARecoveryCodesResponse {
+    codes: string[];
+}
+export interface ForgotPasswordBody {
+    email: string;
+}
+export interface ResetPasswordBody {
+    token: string;
+    password: string;
+}
+export interface UpdateUserInput {
+    name?: string;
+    email?: string;
+    currentPassword?: string;
+    newPassword?: string;
+}
+export interface CreateProjectInput {
+    name: string;
+    description?: string;
+}
+export interface CreateSecretInput {
+    name: string;
+    value: string;
+    notes: string;
+}
+export interface UpdateSecretInput {
+    name?: string;
+    value?: string;
+    notes?: string;
+}
+export type ApiKeyPermission = "read" | "write";
+export interface CreateApiKeyInput {
+    name: string;
+    permissions: ApiKeyPermission[];
+}
+export interface UpdateApiKeyInput {
+    name?: string;
+    isActive?: boolean;
+    addPermissions?: ApiKeyPermission[];
+    removePermissions?: ApiKeyPermission[];
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+/** Request/response DTOs for the Secryn API — mirrored from @repo/shared. */
+export {};

package/index.ts

@@ -0,0 +1 @@
+export { SecrynClient, SecrynApiError } from "./src/client.js";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "secryn",
+  "version": "1.0.0",
+  "description": "Secryn TypeScript SDK — manage secrets, projects, and API keys programmatically",
+  "author": "Secryn",
+  "license": "Apache-2.0",
+  "type": "module",
+  "private": false,
+  "keywords": [
+    "secryn",
+    "secrets",
+    "management",
+    "encryption",
+    "api",
+    "sdk"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/P4ciuf/secryn.git",
+    "directory": "packages/sdk-ts"
+  },
+  "homepage": "https://secryn.xyz",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}