@secureport/core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Jordan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @secureport/core
+
+The shared domain model for [Secureport](https://github.com/agbjordan/secureport).
+The hosted API imports this package the same way a third party would — one
+model, one implementation.
+
+**MIT licensed. Zero runtime dependencies.**
+
+## Status: early scaffold
+
+`0.2.x` is a deliberately small first release, published to prove the release
+path rather than to be built against. **The domain shapes below are being
+replaced wholesale in `0.3.0`** with the full model — `Finding`, `Issue`,
+`Run`, `RunSummary`, `Snapshot` and `Coverage`, content-addressed fingerprints,
+a CVSS-derived severity model, and a `reconcile()` that matches findings to
+issues by fingerprint rather than by title.
+
+If you are evaluating Secureport, wait for `0.3.0`. If you depend on `0.2.x`
+anyway, pin it exactly.
+
+## Install
+
+```sh
+npm install @secureport/core
+```
+
+## Usage
+
+```ts
+import { reconcile, type Finding, type Issue } from '@secureport/core';
+
+const open: Issue[] = [
+  { id: 'ISS-1', title: 'Missing HSTS header', severity: 'medium', status: 'open' },
+];
+
+const findings: Finding[] = [
+  { title: 'Missing HSTS header', severity: 'medium' },
+  { title: 'Directory listing enabled', severity: 'low' },
+];
+
+let n = 2;
+const issues = reconcile(findings, open, () => `ISS-${n++}`);
+// ISS-1 is reused for the HSTS finding; ISS-2 opens for the directory listing.
+```
+
+## The model in one paragraph
+
+The tracked entity is the **issue**, not the finding. A **run** is one
+execution against a target. A **finding** is one detection within one run and
+is immutable — it never carries a status. Findings reconcile into **issues**,
+which persist across runs and carry status, severity and history. That
+distinction is the whole point of the package: two scanners reporting the same
+weakness produce one issue with two sources, not two rows.
+
+## Contracts
+
+Every export is a semver contract. From `0.3.0`, `fingerprint_version` and the
+report JSON schema are versioned public contracts in their own right, and a
+deprecation policy lands before `1.0.0`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './issue.js';
+export * from './reconcile.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './issue.js';
+export * from './reconcile.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/issue.d.ts

@@ -0,0 +1,16 @@
+/** Severity of an {@link Issue}, ordered from most to least urgent by convention. */
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/** Lifecycle state of an {@link Issue}. */
+export type IssueStatus = 'open' | 'triaging' | 'accepted' | 'resolved';
+/**
+ * A tracked issue — the entity Secureport reports on. One or more findings
+ * from one or more scanners can be merged into a single issue; the issue,
+ * not the finding, is what carries status and severity through review.
+ */
+export interface Issue {
+    id: string;
+    title: string;
+    severity: Severity;
+    status: IssueStatus;
+}
+//# sourceMappingURL=issue.d.ts.map

package/dist/issue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../src/issue.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAEvE,2CAA2C;AAC3C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAExE;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;CACrB"}

package/dist/issue.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=issue.js.map

package/dist/issue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue.js","sourceRoot":"","sources":["../src/issue.ts"],"names":[],"mappings":""}

package/dist/reconcile.d.ts

@@ -0,0 +1,15 @@
+import type { Issue } from './issue.js';
+/** A raw scanner result, not yet folded into the tracked issue set. */
+export interface Finding {
+    title: string;
+    severity: Issue['severity'];
+}
+/**
+ * Merges incoming findings into the tracked issue set. A finding whose title
+ * matches an open issue is folded into it; anything new opens an issue.
+ *
+ * Pure: no I/O, no clock, no randomness. Callers supply the id for any issue
+ * this opens via `nextId`.
+ */
+export declare function reconcile(findings: Finding[], openIssues: Issue[], nextId: () => string): Issue[];
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,uEAAuE;AACvE,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,MAAM,GAAG,KAAK,EAAE,CAgBjG"}

package/dist/reconcile.js

@@ -0,0 +1,23 @@
+/**
+ * Merges incoming findings into the tracked issue set. A finding whose title
+ * matches an open issue is folded into it; anything new opens an issue.
+ *
+ * Pure: no I/O, no clock, no randomness. Callers supply the id for any issue
+ * this opens via `nextId`.
+ */
+export function reconcile(findings, openIssues, nextId) {
+    const byTitle = new Map(openIssues.map((issue) => [issue.title, issue]));
+    for (const finding of findings) {
+        const existing = byTitle.get(finding.title);
+        if (!existing) {
+            byTitle.set(finding.title, {
+                id: nextId(),
+                title: finding.title,
+                severity: finding.severity,
+                status: 'open',
+            });
+        }
+    }
+    return [...byTitle.values()];
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,QAAmB,EAAE,UAAmB,EAAE,MAAoB;IACtF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAEzE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE;gBACzB,EAAE,EAAE,MAAM,EAAE;gBACZ,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,MAAM,EAAE,MAAM;aACf,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAC/B,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@secureport/core",
+  "version": "0.2.0",
+  "description": "Shared domain model for Secureport. Imported by the hosted API the same way a third party would.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agbjordan/secureport.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './issue.js';
+export * from './reconcile.js';

package/src/issue.ts

@@ -0,0 +1,17 @@
+/** Severity of an {@link Issue}, ordered from most to least urgent by convention. */
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+
+/** Lifecycle state of an {@link Issue}. */
+export type IssueStatus = 'open' | 'triaging' | 'accepted' | 'resolved';
+
+/**
+ * A tracked issue — the entity Secureport reports on. One or more findings
+ * from one or more scanners can be merged into a single issue; the issue,
+ * not the finding, is what carries status and severity through review.
+ */
+export interface Issue {
+  id: string;
+  title: string;
+  severity: Severity;
+  status: IssueStatus;
+}

package/src/reconcile.ts

@@ -0,0 +1,32 @@
+import type { Issue } from './issue.js';
+
+/** A raw scanner result, not yet folded into the tracked issue set. */
+export interface Finding {
+  title: string;
+  severity: Issue['severity'];
+}
+
+/**
+ * Merges incoming findings into the tracked issue set. A finding whose title
+ * matches an open issue is folded into it; anything new opens an issue.
+ *
+ * Pure: no I/O, no clock, no randomness. Callers supply the id for any issue
+ * this opens via `nextId`.
+ */
+export function reconcile(findings: Finding[], openIssues: Issue[], nextId: () => string): Issue[] {
+  const byTitle = new Map(openIssues.map((issue) => [issue.title, issue]));
+
+  for (const finding of findings) {
+    const existing = byTitle.get(finding.title);
+    if (!existing) {
+      byTitle.set(finding.title, {
+        id: nextId(),
+        title: finding.title,
+        severity: finding.severity,
+        status: 'open',
+      });
+    }
+  }
+
+  return [...byTitle.values()];
+}