@envseal/http-server 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined in Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity exercising
+      permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or Object
+      form, made available under the License, as indicated by a copyright
+      notice that is included in or attached to the work (an example is
+      provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original Work and any Derivative Works thereof, that is
+      intentionally submitted to, or received by, Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal
+      Entity authorized to submit on behalf of the copyright owner. For
+      the purposes of this definition, "submitted" means any form of
+      electronic, verbal, or written communication sent to the Licensor
+      or its representatives, including but not limited to communication
+      on electronic mailing lists, source code control systems, and issue
+      tracking systems that are managed by, or on behalf of, the Licensor
+      for the purpose of discussing and improving the Work, but excluding
+      communication that is conspicuously marked or otherwise designated
+      in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      which a Contribution has been received by Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file, then any
+          Derivative Works that You distribute must include a readable
+          copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE from the Work, provided that
+          such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contribution.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in appropriate
+      comment syntax for the file type. We also recommend that you
+      include a file or class name and date of last modification in
+      the header comment to make it easier to identify the original
+      author and when the file was changed.
+
+         Copyright 2026 The envseal authors
+
+         Licensed under the Apache License, Version 2.0 (the "License");
+         you may not use this file except in compliance with the License.
+         You may obtain a copy of the License at
+
+             http://www.apache.org/licenses/LICENSE-2.0
+
+         Unless required by applicable law or agreed to in writing, software
+         distributed under the License is distributed on an "AS IS" BASIS,
+         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+         See the License for the specific language governing permissions and
+         limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { startHttpServer } from './server.js';
+export type { HttpServerOptions } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+export { startHttpServer } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/openapi.d.ts

@@ -0,0 +1,2 @@
+export declare function generateOpenAPI(port: number): unknown;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.js

@@ -0,0 +1,105 @@
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { SEP_TOOL_NAMES, INPUT_SCHEMAS } from '@envseal/protocol';
+export function generateOpenAPI(port) {
+    const paths = {};
+    for (const toolName of SEP_TOOL_NAMES) {
+        const schema = INPUT_SCHEMAS[toolName];
+        const jsonSchema = zodToJsonSchema(schema);
+        paths[`/v1/${toolName}`] = {
+            post: {
+                summary: `Call ${toolName}`,
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: jsonSchema,
+                        },
+                    },
+                },
+                responses: {
+                    200: {
+                        description: 'Success',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    additionalProperties: true,
+                                },
+                            },
+                        },
+                    },
+                    400: {
+                        description: 'Bad request',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        error: {
+                                            type: 'object',
+                                            properties: {
+                                                code: { type: 'string' },
+                                                userMessage: { type: 'string' },
+                                                retriable: { type: 'boolean' },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    401: {
+                        description: 'Unauthorized',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        error: {
+                                            type: 'object',
+                                            properties: {
+                                                code: { type: 'string' },
+                                                userMessage: { type: 'string' },
+                                                retriable: { type: 'boolean' },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+    }
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: 'envseal SEP/1',
+            version: '1.0.0',
+            description: 'Secret Elicitation Protocol - secure credential collection for AI agents',
+        },
+        servers: [
+            {
+                url: `http://127.0.0.1:${port}`,
+                description: 'Loopback server (127.0.0.1 only)',
+            },
+        ],
+        paths,
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'custom',
+                },
+            },
+        },
+        security: [
+            {
+                bearerAuth: [],
+            },
+        ],
+    };
+}
+//# sourceMappingURL=openapi.js.map

package/dist/server.d.ts

@@ -0,0 +1,21 @@
+import type { Prompter } from '@envseal/prompters';
+export interface HttpServerOptions {
+    root: string;
+    port?: number;
+    token?: string;
+    /**
+     * Surface used to ask the user for env_use confirmation and for consent
+     * before a non-allowlisted verify probe. Defaults to selectPrompter(), which
+     * resolves to `none` in CI -- there those two operations fail with
+     * SEP_NO_INTERACTIVE_SURFACE rather than running unattended.
+     */
+    prompter?: Prompter;
+}
+interface StartResult {
+    url: string;
+    token: string;
+    close(): Promise<void>;
+}
+export declare function startHttpServer(opts: HttpServerOptions): Promise<StartResult>;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,288 @@
+import * as node_http from 'node:http';
+import * as node_crypto from 'node:crypto';
+import * as node_fs from 'node:fs';
+import * as node_os from 'node:os';
+import * as node_path from 'node:path';
+import { Broker } from '@envseal/core';
+import { createProbeApproval, createUseConfirm, dispatch, isSepToolName } from '@envseal/sdk';
+import { selectPrompter } from '@envseal/prompters';
+import { generateOpenAPI } from './openapi.js';
+async function getOrCreateToken(token) {
+    if (token) {
+        return token;
+    }
+    const tokenDir = node_path.join(node_os.homedir(), '.envseal');
+    const tokenFile = node_path.join(tokenDir, 'api-token');
+    // Create directory if needed
+    if (!node_fs.existsSync(tokenDir)) {
+        node_fs.mkdirSync(tokenDir, { recursive: true, mode: 0o700 });
+    }
+    // Check if token file exists
+    if (node_fs.existsSync(tokenFile)) {
+        const tokenBuf = node_fs.readFileSync(tokenFile);
+        return tokenBuf.toString('utf8').trim();
+    }
+    // Generate new token (32 random bytes as hex)
+    const randomBytes = node_crypto.randomBytes(32);
+    const newToken = randomBytes.toString('hex');
+    // Write with 0o600 permissions
+    node_fs.writeFileSync(tokenFile, newToken, { mode: 0o600 });
+    return newToken;
+}
+/**
+ * Constant-time bearer token check. Shared by the /v1 route auth and the
+ * /openapi.json route (N5): the spec used to be served BEFORE the auth check,
+ * so any loopback process could read the API surface without the token.
+ */
+function bearerTokenMatches(authorization, token) {
+    const authHeader = authorization ?? '';
+    const bearerPrefix = 'Bearer ';
+    if (!authHeader.startsWith(bearerPrefix)) {
+        return false;
+    }
+    const providedToken = authHeader.slice(bearerPrefix.length);
+    // Use timing-safe comparison
+    const expectedTokenBuf = Buffer.from(token, 'utf8');
+    const providedTokenBuf = Buffer.from(providedToken, 'utf8');
+    try {
+        return (expectedTokenBuf.length === providedTokenBuf.length &&
+            node_crypto.timingSafeEqual(expectedTokenBuf, providedTokenBuf));
+    }
+    catch {
+        return false;
+    }
+}
+export async function startHttpServer(opts) {
+    const token = await getOrCreateToken(opts.token);
+    const prompter = opts.prompter ?? (await selectPrompter());
+    const surface = { projectRoot: opts.root, prompter: async () => prompter };
+    const broker = new Broker({
+        root: opts.root,
+        prompter,
+        // /v1/env_use is in the OpenAPI document. Without onConfirm the broker has
+        // no way to ask anyone, and exec.ts reports the missing callback as "the
+        // user denied the confirmation" for a user who was never asked.
+        onConfirm: createUseConfirm(surface),
+        // PLAN.md §6.4 probe consent, supplied by no binding before this.
+        onApprovalNeeded: createProbeApproval(surface),
+    });
+    let server = null;
+    let actualPort = 0;
+    const requestHandler = async (req, res) => {
+        // Common response headers
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('Content-Type', 'application/json');
+        // Enforce Host header (DNS rebinding defense)
+        const hostHeader = req.headers.host;
+        const expectedHost = `127.0.0.1:${actualPort}`;
+        if (hostHeader !== expectedHost) {
+            res.writeHead(400);
+            res.end(JSON.stringify({
+                error: {
+                    code: 'INVALID_HOST',
+                    userMessage: 'Invalid Host header',
+                    retriable: false,
+                },
+            }));
+            return;
+        }
+        // Reject requests carrying an Origin header at all (CORS defense).
+        //
+        // Deliberately stricter than the loopback prompter, which must accept the
+        // `Origin: null` a real browser sends on its own form post. Nothing here is
+        // ever fetched by a browser page, so any Origin is a browser reaching a
+        // surface it has no business on.
+        //
+        // `!== undefined`, not truthiness: `Origin:` with an empty value is a
+        // present header, and the old check let it straight through (W3-06).
+        if (req.headers.origin !== undefined) {
+            res.writeHead(400);
+            res.end(JSON.stringify({
+                error: {
+                    code: 'INVALID_ORIGIN',
+                    userMessage: 'Origin header not allowed',
+                    retriable: false,
+                },
+            }));
+            return;
+        }
+        // Handle GET /openapi.json — authenticated like every other route (N5).
+        // The document carries no secrets, but an unauthenticated read let any
+        // loopback process fingerprint the deployment's full route table, and no
+        // caller in this repository depends on the anonymous read.
+        if (req.method === 'GET' && req.url === '/openapi.json') {
+            if (!bearerTokenMatches(req.headers.authorization, token)) {
+                res.writeHead(401);
+                res.end(JSON.stringify({
+                    error: {
+                        code: 'UNAUTHORIZED',
+                        userMessage: 'Missing or invalid authorization',
+                        retriable: false,
+                    },
+                }));
+                return;
+            }
+            const openapi = generateOpenAPI(actualPort);
+            res.writeHead(200);
+            res.end(JSON.stringify(openapi));
+            return;
+        }
+        // All other routes require POST and Bearer token auth
+        if (req.method !== 'POST') {
+            res.writeHead(405);
+            res.end(JSON.stringify({
+                error: {
+                    code: 'METHOD_NOT_ALLOWED',
+                    userMessage: 'Method not allowed',
+                    retriable: false,
+                },
+            }));
+            return;
+        }
+        // Check Authorization header
+        const authHeader = req.headers.authorization ?? '';
+        const bearerPrefix = 'Bearer ';
+        if (!authHeader.startsWith(bearerPrefix)) {
+            res.writeHead(401);
+            res.end(JSON.stringify({
+                error: {
+                    code: 'UNAUTHORIZED',
+                    userMessage: 'Missing or invalid authorization',
+                    retriable: false,
+                },
+            }));
+            return;
+        }
+        if (!bearerTokenMatches(authHeader, token)) {
+            res.writeHead(401);
+            res.end(JSON.stringify({
+                error: {
+                    code: 'UNAUTHORIZED',
+                    userMessage: 'Invalid token',
+                    retriable: false,
+                },
+            }));
+            return;
+        }
+        // Parse URL to get operation name
+        const urlPath = req.url ?? '/';
+        const match = urlPath.match(/^\/v1\/([a-z_]+)$/);
+        if (!match || !match[1]) {
+            res.writeHead(404);
+            res.end(JSON.stringify({
+                error: {
+                    code: 'NOT_FOUND',
+                    userMessage: 'Endpoint not found',
+                    retriable: false,
+                },
+            }));
+            return;
+        }
+        const operationName = match[1];
+        // An unknown operation is a routing failure, not a result. It used to reach
+        // dispatch(), which answered with an error body under HTTP 200 -- so a
+        // client saw success for an endpoint that does not exist (F32). Checked
+        // after auth so an unauthenticated caller cannot map the route table.
+        if (!isSepToolName(operationName)) {
+            res.writeHead(404);
+            res.end(JSON.stringify({
+                error: {
+                    code: 'SEP_UNKNOWN_KEY',
+                    userMessage: `Unknown operation: ${operationName}`,
+                    retriable: false,
+                },
+            }));
+            return;
+        }
+        // Read and validate body
+        const chunks = [];
+        let bodySize = 0;
+        const MAX_BODY_SIZE = 1024 * 1024; // 1 MiB
+        for await (const chunk of req) {
+            bodySize += chunk.length;
+            if (bodySize > MAX_BODY_SIZE) {
+                res.writeHead(413);
+                res.end(JSON.stringify({
+                    error: {
+                        code: 'PAYLOAD_TOO_LARGE',
+                        userMessage: 'Request body too large',
+                        retriable: false,
+                    },
+                }));
+                return;
+            }
+            chunks.push(chunk);
+        }
+        let body;
+        try {
+            const bodyText = Buffer.concat(chunks).toString('utf8');
+            body = bodyText ? JSON.parse(bodyText) : {};
+        }
+        catch {
+            res.writeHead(400);
+            res.end(JSON.stringify({
+                error: {
+                    code: 'INVALID_JSON',
+                    userMessage: 'Invalid JSON in request body',
+                    retriable: false,
+                },
+            }));
+            return;
+        }
+        // Dispatch to SDK
+        try {
+            const result = await dispatch(broker, operationName, body);
+            res.writeHead(200);
+            res.end(JSON.stringify(result));
+        }
+        catch (error) {
+            res.writeHead(500);
+            res.end(JSON.stringify({
+                error: {
+                    code: 'INTERNAL_ERROR',
+                    userMessage: 'An error occurred',
+                    retriable: false,
+                },
+            }));
+        }
+    };
+    return new Promise((resolve, reject) => {
+        server = node_http.createServer(requestHandler);
+        server.listen(opts.port ?? 0, '127.0.0.1', () => {
+            if (!server) {
+                reject(new Error('Server not created'));
+                return;
+            }
+            const addr = server.address();
+            if (!addr || typeof addr === 'string') {
+                reject(new Error('Could not get server address'));
+                return;
+            }
+            actualPort = addr.port;
+            const url = `http://127.0.0.1:${actualPort}`;
+            resolve({
+                url,
+                token,
+                close: async () => {
+                    return new Promise((closeResolve, closeReject) => {
+                        if (!server) {
+                            closeResolve();
+                            return;
+                        }
+                        server.close((err) => {
+                            if (err) {
+                                closeReject(err);
+                            }
+                            else {
+                                closeResolve();
+                            }
+                        });
+                    });
+                },
+            });
+        });
+        server.on('error', reject);
+    });
+}
+//# sourceMappingURL=server.js.map

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@envseal/http-server",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "zod-to-json-schema": "^3.24.1",
+    "@envseal/prompters": "0.1.0",
+    "@envseal/protocol": "0.1.0",
+    "@envseal/sdk": "0.1.0",
+    "@envseal/core": "0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}