@secureport/sdk 0.5.0

package/src/resources/suppression-rules.ts

@@ -0,0 +1,69 @@
+// The SDK's suppression-rules resource: list, create, get and delete.
+import type { Requester } from '../client.js';
+import type { Page, PageQuery } from '../pagination.js';
+import { paginate } from '../pagination.js';
+
+/**
+ * A pre-emptive suppression rule. `createdAt` is an ISO 8601 string, as the
+ * API sends it — parse it yourself if you need a `Date`.
+ */
+export interface SuppressionRule {
+  readonly id: string;
+  readonly orgId: string;
+
+  /** `null` means the rule covers every target in the organisation. */
+  readonly targetId: string | null;
+
+  /** Matched against an issue's vulnerability key; `*` is the only wildcard. */
+  readonly vulnKeyGlob: string;
+  readonly reason: string;
+
+  /** The authenticated actor that created it — never supplied by the caller. */
+  readonly createdBy: string;
+  readonly createdAt: string;
+}
+
+export type SuppressionRulePage = Page<SuppressionRule>;
+
+export interface NewSuppressionRule {
+  /** Omit to cover the whole organisation. */
+  readonly targetId?: string;
+
+  /** Anchored at both ends, so `xss-*` does not match `not-xss-reflected`. */
+  readonly vulnKeyGlob: string;
+  readonly reason: string;
+}
+
+/**
+ * Pre-emptive "never open an issue for this class" rules — the blunt
+ * instrument; per-issue ignore is the default. No update: delete and recreate.
+ */
+export class SuppressionRulesResource {
+  constructor(private readonly request: Requester) {}
+
+  list(query?: PageQuery): Promise<SuppressionRulePage> {
+    return this.request({ method: 'GET', path: '/suppression-rules', query: { ...query } });
+  }
+
+  /** Every rule, across every page, as an async iterator. */
+  listAll(): AsyncIterable<SuppressionRule> {
+    return paginate((page) => this.list({ page }));
+  }
+
+  /** @throws {SecureportError} `not_found` if `targetId` names no target of yours. */
+  create(input: NewSuppressionRule): Promise<SuppressionRule> {
+    return this.request({ method: 'POST', path: '/suppression-rules', body: input });
+  }
+
+  get(id: string): Promise<SuppressionRule> {
+    return this.request({ method: 'GET', path: `/suppression-rules/${encodeURIComponent(id)}` });
+  }
+
+  /** Issues the rule already caused to open as ignored stay ignored. */
+  delete(id: string): Promise<void> {
+    return this.request({
+      method: 'DELETE',
+      path: `/suppression-rules/${encodeURIComponent(id)}`,
+    });
+  }
+}

package/src/resources/targets.ts

@@ -0,0 +1,179 @@
+import type { Requester } from '../client.js';
+import type { Page, PageQuery } from '../pagination.js';
+import { paginate } from '../pagination.js';
+
+/** A target: one thing runs are executed against. */
+export interface Target {
+  readonly id: string;
+  readonly orgId: string;
+
+  /** As it appears on a report cover. */
+  readonly name: string;
+
+  /** A URL, host or repository. */
+  readonly url: string;
+}
+
+export type TargetPage = Page<Target>;
+
+export interface NewTarget {
+  readonly name: string;
+  readonly url: string;
+}
+
+/**
+ * At least one of `name`/`url` is required — the API answers `{}` with a
+ * `422 validation`, not a no-op.
+ */
+export interface TargetPatch {
+  readonly name?: string;
+  readonly url?: string;
+}
+
+export type VerificationMethod = 'dns_txt' | 'http_file';
+export type VerificationState = 'unverified' | 'verified';
+
+/**
+ * The target's current verification state. Never carries the token — see
+ * {@link IssuedTargetVerification}, the one response that does.
+ *
+ * Date fields are ISO 8601 strings, as the API sends them — this type is
+ * SDK-local (no `@secureport/core` equivalent exists), so there is no
+ * shared revival logic to lean on; parse them yourself if you need `Date`.
+ */
+export interface TargetVerification {
+  readonly method: VerificationMethod | null;
+  readonly state: VerificationState;
+  readonly issuedAt: string | null;
+
+  /** Set only while a rotated token's grace period is still active. */
+  readonly previousExpiresAt: string | null;
+}
+
+export interface NewTargetVerification {
+  readonly method: VerificationMethod;
+}
+
+/**
+ * The response to issuing (or rotating) a verification token.
+ *
+ * **The token appears here and nowhere else** — {@link TargetVerification}
+ * never carries it, and there is no recovery endpoint. Losing it means
+ * issuing a new one, which may reset `state` to `unverified` (see
+ * {@link TargetsResource.issueVerification}).
+ *
+ * `recordName`/`recordValue` are present for `method: 'dns_txt'`;
+ * `filePath`/`fileContents` for `method: 'http_file'` — a discriminated
+ * pair the wire schema does not enforce, so narrow on `method` yourself.
+ */
+export interface IssuedTargetVerification extends Omit<TargetVerification, 'method'> {
+  readonly method: VerificationMethod;
+  readonly token: string;
+  readonly summary: string;
+  readonly recordName?: string;
+  readonly recordValue?: string;
+  readonly filePath?: string;
+  readonly fileContents?: string;
+}
+
+/** The result of one verification check — evidence, not a status flag. */
+export interface TargetVerificationCheckResult {
+  /** This check's own evidence row id — a fresh one every call, whether it passed or failed. */
+  readonly id: string;
+  readonly verified: boolean;
+  readonly state: VerificationState;
+  readonly method: VerificationMethod;
+  readonly checkedAt: string;
+  readonly expected: string;
+  readonly observed: string | null;
+  readonly message: string;
+}
+
+/**
+ * Targets, and the per-target verification flow a hosted scan (`kind:
+ * 'scan'`) requires before it can start — see `POST /runs`'s
+ * `verification_required` gate.
+ */
+export class TargetsResource {
+  constructor(private readonly request: Requester) {}
+
+  list(query?: PageQuery): Promise<TargetPage> {
+    return this.request({ method: 'GET', path: '/targets', query: { ...query } });
+  }
+
+  /** Every target, across every page, as an async iterator. */
+  listAll(): AsyncIterable<Target> {
+    return paginate((page) => this.list({ page }));
+  }
+
+  create(input: NewTarget): Promise<Target> {
+    return this.request({ method: 'POST', path: '/targets', body: input });
+  }
+
+  get(id: string): Promise<Target> {
+    return this.request({ method: 'GET', path: `/targets/${encodeURIComponent(id)}` });
+  }
+
+  /**
+   * **Changing `url` silently un-verifies the target** — the stored
+   * verification named the old host, and the API drops `state` to
+   * `unverified` as part of this same call. A caller relying on the target
+   * staying verified across a URL change needs to re-verify afterwards.
+   */
+  update(id: string, patch: TargetPatch): Promise<Target> {
+    return this.request({
+      method: 'PATCH',
+      path: `/targets/${encodeURIComponent(id)}`,
+      body: patch,
+    });
+  }
+
+  /** @throws {SecureportError} `conflict` if the target has run or issue history. */
+  delete(id: string): Promise<void> {
+    return this.request({ method: 'DELETE', path: `/targets/${encodeURIComponent(id)}` });
+  }
+
+  getVerification(id: string): Promise<TargetVerification> {
+    return this.request({ method: 'GET', path: `/targets/${encodeURIComponent(id)}/verification` });
+  }
+
+  /**
+   * Issues a fresh verification token, or rotates the current one — decided
+   * server-side, not by this method: calling with the **same `method`** as
+   * an already-verified target **rotates** (the target stays `verified`,
+   * and the old token keeps working for a 24-hour grace period). Calling
+   * with any other method, or while unverified, **re-issues** and resets
+   * `state` to `unverified` until the new token is checked.
+   */
+  issueVerification(id: string, input: NewTargetVerification): Promise<IssuedTargetVerification> {
+    return this.request({
+      method: 'POST',
+      path: `/targets/${encodeURIComponent(id)}/verification`,
+      body: input,
+    });
+  }
+
+  /**
+   * Runs the verification check now, fresh — never trusts a stored flag.
+   * **Promote-only**: a match sets `state: 'verified'`; a mismatch or
+   * unreachable record is recorded as evidence but never demotes a target
+   * that is already verified. Writes a new evidence row every call, whether
+   * it passes or fails — not a no-op check.
+   *
+   * @throws {SecureportError} `conflict` if no token has been issued yet.
+   */
+  verify(id: string): Promise<TargetVerificationCheckResult> {
+    return this.request({ method: 'POST', path: `/targets/${encodeURIComponent(id)}/verify` });
+  }
+
+  /**
+   * Revokes the current token outright — idempotent; revoking an
+   * already-unverified target is a clean no-op, not an error.
+   */
+  revokeVerification(id: string): Promise<void> {
+    return this.request({
+      method: 'DELETE',
+      path: `/targets/${encodeURIComponent(id)}/verification`,
+    });
+  }
+}