@slicedearth/whoisleuth-cli 1.47.4 → 2.0.0

package/packages/contracts/cli-command-catalogue.mjs

@@ -0,0 +1,2 @@
+export const CLI_COMMAND_CATALOGUE_SCHEMA = 'whoisleuth.cli.command-catalogue';
+export const CLI_COMMAND_CATALOGUE_VERSION = 1;

package/packages/contracts/cli-lookup.mjs

@@ -0,0 +1,394 @@
+import { defineSchemaCompatibility } from "./schema-compatibility.mjs";
+import { defineSchemaLifecycleFamily } from "./schema-lifecycle.mjs";
+export const CLI_LOOKUP_SCHEMA = 'whoisleuth.cli.lookup';
+export const PUBLIC_CLI_LOOKUP_VERSION = 1;
+export const CLI_LOOKUP_VERSION = 2;
+export const SUPPORTED_CLI_LOOKUP_VERSIONS = Object.freeze([
+    PUBLIC_CLI_LOOKUP_VERSION,
+    CLI_LOOKUP_VERSION,
+]);
+export const MAX_CLI_LOOKUP_BYTES = 8 * 1024 * 1024;
+export const MAX_CLI_LOOKUP_STRING_LENGTH = 1_024;
+export const MAX_CLI_LOOKUP_JSON_DEPTH = 48;
+export const MAX_CLI_LOOKUP_JSON_KEYS = 50_000;
+export const MAX_CLI_LOOKUP_JSON_VALUES = 100_000;
+export const MAX_CLI_LOOKUP_JSON_CONTAINER_ITEMS = 10_000;
+export const CLI_LOOKUP_QUERY_TYPES = Object.freeze([
+    'domain',
+    'ipv4',
+    'ipv6',
+    'asn',
+]);
+export const CLI_LOOKUP_REQUIRED_ROOT_KEYS = Object.freeze([
+    'schema',
+    'version',
+    'generatedAt',
+    'mode',
+    'query',
+    'type',
+    'diagnostics',
+]);
+export const CLI_LOOKUP_OPTIONAL_ROOT_KEYS = Object.freeze([
+    'inputHostname',
+    'registrableDomain',
+    'isSubdomain',
+    'rdap',
+    'whois',
+    'availability',
+    'registryInsights',
+    'reverseDns',
+    'networkContext',
+    'securityTxt',
+    'sslbl',
+    'threatIntelligence',
+    'collectionContext',
+]);
+export const CLI_LOOKUP_DIAGNOSTIC_REQUIRED_KEYS = Object.freeze([
+    'rdap',
+    'whois',
+]);
+export const CLI_LOOKUP_COMPATIBILITY = defineSchemaCompatibility({
+    id: 'cli.lookup',
+    kind: 'cli_document',
+    schema: CLI_LOOKUP_SCHEMA,
+    currentVersion: CLI_LOOKUP_VERSION,
+    supportedVersions: SUPPORTED_CLI_LOOKUP_VERSIONS,
+    acceptsUnversionedLegacy: false,
+    futureVersionBehavior: 'reject',
+    migration: 'read_only',
+    writeSemantics: 'normalized_rewrite',
+    byteBudget: MAX_CLI_LOOKUP_BYTES,
+    owner: 'packages/contracts/cli-lookup.mts',
+    note: 'Saved Lookup documents preserve version 1 domain, IP and ASN compatibility while version 2 can additionally retain bounded Deep homepage metadata.',
+});
+export const CLI_LOOKUP_SCHEMA_LIFECYCLE = defineSchemaLifecycleFamily({
+    id: 'cli-lookup',
+    owner: 'packages/contracts/cli-lookup.mts',
+    privacy: 'analyst_authored_sensitive',
+    compatibility: [CLI_LOOKUP_COMPATIBILITY],
+    contracts: [
+        {
+            compatibilityId: CLI_LOOKUP_COMPATIBILITY.id,
+            schema: CLI_LOOKUP_SCHEMA,
+            version: PUBLIC_CLI_LOOKUP_VERSION,
+            role: 'document',
+            lifecycle: 'legacy',
+            readable: true,
+            emitted: false,
+            exactKeys: false,
+            extensionPolicy: 'preserve_bounded',
+            futureVersionBehaviour: 'reject',
+            migrationTarget: null,
+            canonicalisation: null,
+            byteBudget: MAX_CLI_LOOKUP_BYTES,
+            fixtureIds: ['cli-lookup-v1', 'cli-lookup-asn-v1'],
+        },
+        {
+            compatibilityId: CLI_LOOKUP_COMPATIBILITY.id,
+            schema: CLI_LOOKUP_SCHEMA,
+            version: CLI_LOOKUP_VERSION,
+            role: 'document',
+            lifecycle: 'current',
+            readable: true,
+            emitted: true,
+            exactKeys: false,
+            extensionPolicy: 'preserve_bounded',
+            futureVersionBehaviour: 'reject',
+            migrationTarget: null,
+            canonicalisation: null,
+            byteBudget: MAX_CLI_LOOKUP_BYTES,
+            fixtureIds: ['cli-lookup-v2', 'cli-lookup-asn-v2'],
+        },
+    ],
+    fixtures: [
+        {
+            id: 'cli-lookup-v1',
+            path: 'test/fixtures/cli-lookup-v1.json',
+            bytes: 952,
+            sha256: '0e6601693e384b29285ead97b20947c3a464baf2521277901ff86ad5a6e3a59e',
+            contentDigestSha256: null,
+            schema: CLI_LOOKUP_SCHEMA,
+            version: PUBLIC_CLI_LOOKUP_VERSION,
+            role: 'historical',
+            expectation: 'accepted_exact',
+            expectedOutputFixtureId: null,
+            scope: 'repository',
+        },
+        {
+            id: 'cli-lookup-v2',
+            path: 'test/fixtures/cli-lookup-v2.json',
+            bytes: 4_410,
+            sha256: 'd98356ede18ddd12fde8cf10b0cfa43c42f6c9a09f1951e0605e1ec912892778',
+            contentDigestSha256: null,
+            schema: CLI_LOOKUP_SCHEMA,
+            version: CLI_LOOKUP_VERSION,
+            role: 'current',
+            expectation: 'accepted_exact',
+            expectedOutputFixtureId: null,
+            scope: 'repository',
+        },
+        {
+            id: 'cli-lookup-asn-v1',
+            path: 'test/fixtures/cli-lookup-asn-v1.json',
+            bytes: 714,
+            sha256: 'bb06e18c67527e559a039f7f826d4d605d7581a556e2e6e511c461ba97dcfdef',
+            contentDigestSha256: null,
+            schema: CLI_LOOKUP_SCHEMA,
+            version: PUBLIC_CLI_LOOKUP_VERSION,
+            role: 'historical',
+            expectation: 'accepted_exact',
+            expectedOutputFixtureId: null,
+            scope: 'repository',
+        },
+        {
+            id: 'cli-lookup-asn-v2',
+            path: 'test/fixtures/cli-lookup-asn-v2.json',
+            bytes: 714,
+            sha256: 'a3ee74df02050d6efd935784734c8c4cfd5fcb9833393de68935f5040faf2856',
+            contentDigestSha256: null,
+            schema: CLI_LOOKUP_SCHEMA,
+            version: CLI_LOOKUP_VERSION,
+            role: 'current',
+            expectation: 'accepted_exact',
+            expectedOutputFixtureId: null,
+            scope: 'repository',
+        },
+    ],
+    metadata: {
+        metadataVersion: 3,
+        enforcement: 'declarative_only',
+        shapes: [
+            {
+                id: 'cli-lookup.document.v1',
+                schema: CLI_LOOKUP_SCHEMA,
+                versions: [PUBLIC_CLI_LOOKUP_VERSION],
+                objects: [
+                    { path: '$', requiredKeys: CLI_LOOKUP_REQUIRED_ROOT_KEYS, optionalKeys: CLI_LOOKUP_OPTIONAL_ROOT_KEYS, unknownKeys: 'preserve_bounded' },
+                    { path: '$.diagnostics', requiredKeys: CLI_LOOKUP_DIAGNOSTIC_REQUIRED_KEYS, optionalKeys: [], unknownKeys: 'preserve_bounded' },
+                    { path: '$.diagnostics.rdap', requiredKeys: ['status'], optionalKeys: [], unknownKeys: 'preserve_bounded' },
+                    { path: '$.diagnostics.whois', requiredKeys: ['status'], optionalKeys: [], unknownKeys: 'preserve_bounded' },
+                ],
+                fixedArrays: [],
+                normalisation: 'preserve_bounded_document',
+                target: null,
+            },
+            {
+                id: 'cli-lookup.document.v2',
+                schema: CLI_LOOKUP_SCHEMA,
+                versions: [CLI_LOOKUP_VERSION],
+                objects: [
+                    { path: '$', requiredKeys: CLI_LOOKUP_REQUIRED_ROOT_KEYS, optionalKeys: CLI_LOOKUP_OPTIONAL_ROOT_KEYS, unknownKeys: 'preserve_bounded' },
+                    { path: '$.diagnostics', requiredKeys: CLI_LOOKUP_DIAGNOSTIC_REQUIRED_KEYS, optionalKeys: [], unknownKeys: 'preserve_bounded' },
+                    { path: '$.diagnostics.rdap', requiredKeys: ['status'], optionalKeys: [], unknownKeys: 'preserve_bounded' },
+                    { path: '$.diagnostics.whois', requiredKeys: ['status'], optionalKeys: [], unknownKeys: 'preserve_bounded' },
+                ],
+                fixedArrays: [],
+                normalisation: 'preserve_bounded_document',
+                target: null,
+            },
+        ],
+        boundProfiles: [
+            {
+                id: 'cli-lookup.document-bounds.v1',
+                bounds: [
+                    { id: 'raw-bytes', path: '$', phase: 'raw_intake', unit: 'bytes', minimum: 1, maximum: MAX_CLI_LOOKUP_BYTES, handling: 'reject' },
+                    { id: 'serialised-bytes', path: '$', phase: 'serialised', unit: 'bytes', minimum: 1, maximum: MAX_CLI_LOOKUP_BYTES, handling: 'reject' },
+                    { id: 'json-depth', path: '$', phase: 'pre_accumulation', unit: 'depth', minimum: 0, maximum: MAX_CLI_LOOKUP_JSON_DEPTH, handling: 'reject' },
+                    { id: 'json-keys', path: '$', phase: 'pre_accumulation', unit: 'keys', minimum: 1, maximum: MAX_CLI_LOOKUP_JSON_KEYS, handling: 'reject' },
+                    { id: 'json-values', path: '$', phase: 'pre_accumulation', unit: 'values', minimum: 1, maximum: MAX_CLI_LOOKUP_JSON_VALUES, handling: 'reject' },
+                    { id: 'json-container-items', path: '$', phase: 'pre_accumulation', unit: 'items', minimum: 1, maximum: MAX_CLI_LOOKUP_JSON_CONTAINER_ITEMS, handling: 'reject' },
+                    { id: 'query-characters', path: '$.query', phase: 'normalised', unit: 'characters', minimum: 1, maximum: MAX_CLI_LOOKUP_STRING_LENGTH, handling: 'reject' },
+                    { id: 'generated-at-characters', path: '$.generatedAt', phase: 'normalised', unit: 'characters', minimum: 1, maximum: MAX_CLI_LOOKUP_STRING_LENGTH, handling: 'reject' },
+                ],
+            },
+        ],
+        hooks: [
+            { id: 'cli-lookup.cli.build', role: 'builder', runtime: 'cli', module: 'cli/saved-lookup.mts', exportName: 'buildCliLookupDocument' },
+            { id: 'cli-lookup.cli.normalise', role: 'normaliser', runtime: 'cli', module: 'cli/saved-lookup.mts', exportName: 'normalizeCliLookupDocument' },
+            { id: 'cli-lookup.cli.parse-all', role: 'normaliser', runtime: 'cli', module: 'cli/saved-lookup.mts', exportName: 'parseCliLookupDocument' },
+            { id: 'cli-lookup.cli.parse-domain', role: 'normaliser', runtime: 'cli', module: 'cli/saved-lookup.mts', exportName: 'parseSavedLookupDocument' },
+            { id: 'cli-lookup.cli.serialise', role: 'serialiser', runtime: 'cli', module: 'cli/saved-lookup.mts', exportName: 'serializeCliLookupDocument' },
+            { id: 'cli-lookup.cli.source-report', role: 'reviewer', runtime: 'cli', module: 'cli/source-reliability.mts', exportName: 'buildSourceReliabilityReport' },
+            { id: 'cli-lookup.cli.offline-verify', role: 'structure_validator', runtime: 'cli', module: 'cli/artifact-verify.mts', exportName: 'verifyOfflineArtifact' },
+            { id: 'cli-lookup.cli.sharing-review', role: 'sharing_reviewer', runtime: 'cli', module: 'cli/sharing-review.mts', exportName: 'buildSharingReview' },
+        ],
+        serialisationProfiles: [
+            {
+                id: 'cli-lookup.json.v1-v2',
+                schema: CLI_LOOKUP_SCHEMA,
+                versions: [PUBLIC_CLI_LOOKUP_VERSION, CLI_LOOKUP_VERSION],
+                mediaType: 'application/json',
+                encoding: 'utf-8',
+                bom: false,
+                indentSpaces: 2,
+                terminalLf: true,
+                propertyOrder: 'source_insertion',
+                canonicalisation: null,
+                integrity: 'none',
+                serializerHookId: 'cli-lookup.cli.serialise',
+                verifierHookIds: [],
+            },
+        ],
+        privacyProfiles: [
+            {
+                id: 'cli-lookup.sensitive-collection.v1',
+                classification: 'analyst_authored_sensitive',
+                projection: 'full_manifest',
+                includedCategories: ['target-identifiers', 'query-and-mode', 'raw-rdap-publications', 'raw-whois-responses', 'published-contacts', 'source-endpoints', 'source-timings', 'normalised-evidence', 'collection-context'],
+                excludedCategories: ['credentials', 'cookies', 'sessions', 'authorisation-material'],
+                notePolicy: 'not_applicable',
+                retention: 'operator_controlled_output',
+                network: 'explicit_bounded_passive_fast_or_deep',
+                sharingReview: 'required',
+            },
+            {
+                id: 'cli-lookup.sensitive-file.v1',
+                classification: 'analyst_authored_sensitive',
+                projection: 'full_manifest',
+                includedCategories: ['target-identifiers', 'query-and-mode', 'raw-rdap-publications', 'raw-whois-responses', 'published-contacts', 'source-endpoints', 'source-timings', 'normalised-evidence', 'collection-context'],
+                excludedCategories: ['credentials', 'cookies', 'sessions', 'authorisation-material'],
+                notePolicy: 'not_applicable',
+                retention: 'deliberate_local_file',
+                network: 'none',
+                sharingReview: 'required',
+            },
+            {
+                id: 'cli-lookup.metadata-report.v1',
+                classification: 'metadata_only',
+                projection: 'metadata_only',
+                includedCategories: ['schema-and-version', 'source-state-counts', 'bounded-timings', 'integrity-state'],
+                excludedCategories: ['target-identifiers', 'query-and-mode', 'raw-rdap-publications', 'raw-whois-responses', 'published-contacts', 'source-endpoints', 'normalised-evidence', 'collection-context'],
+                notePolicy: 'not_applicable',
+                retention: 'transient_report',
+                network: 'none',
+                sharingReview: 'not_applicable',
+            },
+            {
+                id: 'cli-lookup.source-report.v1',
+                classification: 'metadata_only',
+                projection: 'metadata_only',
+                includedCategories: ['schema-and-version', 'source-state-counts', 'bounded-timings', 'truncation-and-rate-limit-counts', 'aggregate-lookup-mode-counts'],
+                excludedCategories: ['target-identifiers', 'query-values', 'per-document-linkage', 'raw-rdap-publications', 'raw-whois-responses', 'published-contacts', 'source-endpoints', 'normalised-evidence', 'collection-context'],
+                notePolicy: 'not_applicable',
+                retention: 'transient_report',
+                network: 'none',
+                sharingReview: 'not_applicable',
+            },
+        ],
+        expiryProfiles: [
+            {
+                id: 'cli-lookup.expiry.not-applicable.v1',
+                field: null,
+                anchor: null,
+                handling: 'not_applicable',
+                phase: 'not_applicable',
+                maximumLifetimeDays: null,
+            },
+        ],
+        consumerEdges: [
+            {
+                id: 'cli-lookup.cli-build',
+                plane: 'cli',
+                operation: 'collect-and-serialise-fast-or-deep',
+                acceptedContracts: [],
+                emittedContract: { schema: CLI_LOOKUP_SCHEMA, version: CLI_LOOKUP_VERSION },
+                shapeIds: ['cli-lookup.document.v2'],
+                boundProfileIds: ['cli-lookup.document-bounds.v1'],
+                hookIds: ['cli-lookup.cli.build', 'cli-lookup.cli.serialise'],
+                serialisationProfileId: 'cli-lookup.json.v1-v2',
+                privacyProfileId: 'cli-lookup.sensitive-collection.v1',
+                expiryPolicyId: 'cli-lookup.expiry.not-applicable.v1',
+                requestMode: 'explicit_bounded_passive_fast_or_deep',
+                retentionEffect: 'operator_controlled_output',
+                bindingState: 'declared_unenforced',
+                policyState: 'current',
+            },
+            {
+                id: 'cli-lookup.cli-read-all',
+                plane: 'cli',
+                operation: 'read-all-query-types',
+                acceptedContracts: [{ schema: CLI_LOOKUP_SCHEMA, versions: [PUBLIC_CLI_LOOKUP_VERSION, CLI_LOOKUP_VERSION], mode: 'direct' }],
+                emittedContract: null,
+                shapeIds: ['cli-lookup.document.v1', 'cli-lookup.document.v2'],
+                boundProfileIds: ['cli-lookup.document-bounds.v1'],
+                hookIds: ['cli-lookup.cli.parse-all'],
+                serialisationProfileId: null,
+                privacyProfileId: 'cli-lookup.sensitive-file.v1',
+                expiryPolicyId: 'cli-lookup.expiry.not-applicable.v1',
+                requestMode: 'none',
+                retentionEffect: 'deliberate_local_file',
+                bindingState: 'declared_unenforced',
+                policyState: 'current',
+            },
+            {
+                id: 'cli-lookup.cli-read-domain',
+                plane: 'cli',
+                operation: 'read-domain-only',
+                acceptedContracts: [{ schema: CLI_LOOKUP_SCHEMA, versions: [PUBLIC_CLI_LOOKUP_VERSION, CLI_LOOKUP_VERSION], mode: 'direct', discriminator: { path: '$.type', values: ['domain'] } }],
+                emittedContract: null,
+                shapeIds: ['cli-lookup.document.v1', 'cli-lookup.document.v2'],
+                boundProfileIds: ['cli-lookup.document-bounds.v1'],
+                hookIds: ['cli-lookup.cli.parse-domain'],
+                serialisationProfileId: null,
+                privacyProfileId: 'cli-lookup.sensitive-file.v1',
+                expiryPolicyId: 'cli-lookup.expiry.not-applicable.v1',
+                requestMode: 'none',
+                retentionEffect: 'deliberate_local_file',
+                bindingState: 'declared_unenforced',
+                policyState: 'current',
+            },
+            {
+                id: 'cli-lookup.cli-source-report',
+                plane: 'cli',
+                operation: 'build-source-reliability-report',
+                acceptedContracts: [{ schema: CLI_LOOKUP_SCHEMA, versions: [PUBLIC_CLI_LOOKUP_VERSION, CLI_LOOKUP_VERSION], mode: 'direct' }],
+                emittedContract: null,
+                shapeIds: ['cli-lookup.document.v1', 'cli-lookup.document.v2'],
+                boundProfileIds: ['cli-lookup.document-bounds.v1'],
+                hookIds: ['cli-lookup.cli.normalise', 'cli-lookup.cli.source-report'],
+                serialisationProfileId: null,
+                privacyProfileId: 'cli-lookup.source-report.v1',
+                expiryPolicyId: 'cli-lookup.expiry.not-applicable.v1',
+                requestMode: 'none',
+                retentionEffect: 'transient_report',
+                bindingState: 'declared_unenforced',
+                policyState: 'current',
+            },
+            {
+                id: 'cli-lookup.cli-offline-verify',
+                plane: 'cli',
+                operation: 'verify-structure',
+                acceptedContracts: [{ schema: CLI_LOOKUP_SCHEMA, versions: [PUBLIC_CLI_LOOKUP_VERSION, CLI_LOOKUP_VERSION], mode: 'direct' }],
+                emittedContract: null,
+                shapeIds: ['cli-lookup.document.v1', 'cli-lookup.document.v2'],
+                boundProfileIds: ['cli-lookup.document-bounds.v1'],
+                hookIds: ['cli-lookup.cli.parse-all', 'cli-lookup.cli.offline-verify'],
+                serialisationProfileId: null,
+                privacyProfileId: 'cli-lookup.metadata-report.v1',
+                expiryPolicyId: 'cli-lookup.expiry.not-applicable.v1',
+                requestMode: 'none',
+                retentionEffect: 'transient_report',
+                bindingState: 'declared_unenforced',
+                policyState: 'current',
+            },
+            {
+                id: 'cli-lookup.cli-sharing-review',
+                plane: 'cli',
+                operation: 'build-redacted-sharing-review',
+                acceptedContracts: [{ schema: CLI_LOOKUP_SCHEMA, versions: [PUBLIC_CLI_LOOKUP_VERSION, CLI_LOOKUP_VERSION], mode: 'direct' }],
+                emittedContract: null,
+                shapeIds: ['cli-lookup.document.v1', 'cli-lookup.document.v2'],
+                boundProfileIds: ['cli-lookup.document-bounds.v1'],
+                hookIds: ['cli-lookup.cli.parse-all', 'cli-lookup.cli.sharing-review'],
+                serialisationProfileId: null,
+                privacyProfileId: 'cli-lookup.metadata-report.v1',
+                expiryPolicyId: 'cli-lookup.expiry.not-applicable.v1',
+                requestMode: 'none',
+                retentionEffect: 'transient_report',
+                bindingState: 'declared_unenforced',
+                policyState: 'current',
+            },
+        ],
+        consumerRelationships: [],
+    },
+});