Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

16.5 KB
Raw Blame
/**
 * Public contract shape for `inspect_apk_signature` and the pure signing
 * posture derivation. The domain owns the schema so CLI and MCP present
 * identical, validated facts. Certificate facts are plain data extracted by the
 * adapter (via the platform X.509 parser); this module never parses DER itself.
 */
import { z } from "zod";

import type { EvidenceSubjectTarget } from "../evidence.js";
import { digestSchema as digest } from "../digests.js";

/**
 * A signer certificate. `sha256_fingerprint` is always SHA-256 over the raw
 * embedded DER (exactly what apksig/apksigner hash); the parsed X.509 facts are
 * individually null when the platform parser cannot read the DER. The whole
 * object is null only when the signer carries no certificate at all.
 */
const certificate = z
  .strictObject({
    sha256_fingerprint: digest,
    subject: z.string().nullable(),
    issuer: z.string().nullable(),
    serial_number: z.string().nullable(),
    /** ISO 8601. */
    not_before: z.string().nullable(),
    /** ISO 8601. */
    not_after: z.string().nullable(),
    public_key_algorithm: z.string().nullable(),
  })
  .nullable();

const digestEntry = z.strictObject({
  uninterpreted_bytes: z.int().nonnegative(),
  signature_algorithm_id: z.int().min(0).max(0xffffffff),
  algorithm: z.enum(["sha256", "sha512", "verity-sha256", "unknown"]),
  declared_digest_hex: z.string().regex(/^(?:[a-f0-9]{2})*$/),
  /**
   * Whether the DECLARED content digest equals the digest recomputed over the
   * current bytes; null when not recomputed. Not a signature verification:
   * anyone who changes the bytes can recompute and replace the declared digest.
   */
  matches_apk: z.boolean().nullable(),
});

export const apkSignerSchema = z.strictObject({
  uninterpreted_signed_data_bytes: z.int().nonnegative(),
  uninterpreted_signer_bytes: z.int().nonnegative(),
  certificate,
  digests: z.array(digestEntry),
  signatures: z.array(
    z.strictObject({
      signature_algorithm_id: z.int().min(0).max(0xffffffff),
      algorithm: digestEntry.shape.algorithm,
      signature_bytes: z.int().nonnegative(),
      uninterpreted_bytes: z.int().nonnegative(),
    }),
  ),
  public_key_bytes: z.int().nonnegative(),
  min_sdk: z.number().int().nullable(),
  max_sdk: z.number().int().nullable(),
});

const lineageNode = z.strictObject({
  certificate,
  /**
   * Raw capability flags RETAINED by this node's own certificate after the
   * rotation (kept raw so unknown future bits are preserved).
   */
  flags: z.number().int().nonnegative(),
  capabilities: z.strictObject({
    installed_data: z.boolean(),
    shared_uid: z.boolean(),
    permission: z.boolean(),
    rollback: z.boolean(),
    auth: z.boolean(),
  }),
});

export const apkSignerV3Schema = apkSignerSchema.extend({
  /**
   * The proof-of-rotation lineage the APK DECLARES, oldest signer first. Node
   * signatures are not verified. `decode_error` is set (and `lineage` empty)
   * when the attribute is present but could not be decoded.
   */
  rotation: z.strictObject({
    present: z.boolean(),
    lineage: z.array(lineageNode),
    decode_error: z.string().nullable(),
  }),
});

/**
 * A v1 (JAR) signer: one signature block, its `.SF` partner and what the
 * block's PKCS#7 SignedData declares. Nothing is verified.
 */
const v1Signer = z.strictObject({
  signature_file: z.string(),
  block_file: z.string(),
  /**
   * The certificate the block's one SignerInfo names (by issuerAndSerialNumber
   * or subjectKeyIdentifier), with the same facts as a v2/v3 signer. Null when
   * the block could not be decoded, has other than one SignerInfo, or its
   * SignerInfo names no certificate the block carries (identity unknown).
   */
  certificate,
  /** Every certificate the SignedData carries, in block order. */
  certificates: z.array(
    z.strictObject({
      sha256_fingerprint: digest,
      subject: z.string().nullable(),
    }),
  ),
  signer_infos: z.array(
    z.strictObject({
      identified_by: z.enum(["issuer-and-serial", "subject-key-identifier"]),
      /** The named certificate's fingerprint; null when none in the block matches. */
      certificate_sha256: digest.nullable(),
      digest_algorithm_oid: z.string(),
      signature_algorithm_oid: z.string(),
    }),
  ),
  /** Why the block could not be read (malformed, unsupported or over a bound); never silently empty. */
  decode_error: z.string().nullable(),
});

const SCHEME = z.enum(["none", "v1", "v2", "v3", "v3.1"]);

export const apkSignatureResultSchema = z.strictObject({
  artifact: z.strictObject({
    path: z.string().min(1),
    sha256: digest,
    bytes: z.number().int().nonnegative(),
  }),
  schemes: z.strictObject({
    v1: z.strictObject({
      /** Structural: META-INF signature files exist (not platform applicability). */
      present: z.boolean(),
      has_manifest: z.boolean(),
      signature_files: z.array(z.string()),
      block_files: z.array(z.string()),
      /** Signature blocks paired with their `.SF` file, in central-directory order. */
      signers: z.array(v1Signer),
    }),
    v2: z.strictObject({
      present: z.boolean(),
      signers: z.array(apkSignerSchema),
      uninterpreted_bytes: z.int().nonnegative(),
    }),
    v3: z.strictObject({
      present: z.boolean(),
      signers: z.array(apkSignerV3Schema),
      uninterpreted_bytes: z.int().nonnegative(),
    }),
    "v3.1": z.strictObject({
      present: z.boolean(),
      signers: z.array(apkSignerV3Schema),
      uninterpreted_bytes: z.int().nonnegative(),
    }),
  }),
  /**
   * The source stamp the APK declares (V2 block preferred over V1, as apksig
   * does). `certificate` is the declared stamp certificate; it is null when no
   * stamp is present or when `decode_error` says why it could not be read.
   * Stamp signatures are not verified.
   */
  source_stamp: z.strictObject({
    present: z.boolean(),
    certificate,
    decode_error: z.string().nullable(),
  }),
  /** Derived from the observed and declared facts above; not separately observed. */
  posture: z.strictObject({
    /**
     * v1 present and no v2/v3/v3.1 block. The v1 X-Android-APK-Signed marker
     * is not read, so this cannot distinguish a v1-only APK from one whose
     * v2/v3 block was removed.
     */
    v1_only: z.boolean(),
    /**
     * Observed: every present block scheme (v2/v3/v3.1) presents the same set
     * of signer certificates. Null when no block scheme has a signer, or when
     * any signer carries no certificate (identity unknown).
     */
    schemes_agree_on_signer: z.boolean().nullable(),
    /**
     * Declared: the signers differ, but every one appears in a rotation
     * lineage the APK declares. Unverified — an APK can declare any lineage.
     * Null when a signer's identity is unknown, or when the signers differ and
     * a declared lineage could not be decoded.
     */
    signer_change_declared_by_rotation: z.boolean().nullable(),
    /**
     * Observed: the set of v1 signer certificates equals what the lowest
     * present block scheme with signers (v2, else v3, else v3.1) expects v1 to
     * carry: its signer set, or, for a v3/v3.1 signer that declares a rotation
     * lineage, that lineage's first (original) certificate, as apksig requires.
     * False is notable: the JAR signature names a different key. Null when v1
     * or a block scheme is absent, any signer's identity is unknown
     * (including a v1 SignerInfo identified by subjectKeyIdentifier, which
     * apksig cannot resolve), or a declared lineage's original certificate
     * cannot be identified (a limitation then says why).
     */
    v1_signers_match_block_signers: z.boolean().nullable(),
    rotation_present: z.boolean(),
    source_stamp_present: z.boolean(),
    strongest_scheme: SCHEME,
    /**
     * Every recomputed declared content digest equals the current bytes; null
     * when none was recomputed. Not a signature verification.
     */
    self_consistent: z.boolean().nullable(),
  }),
  runtime_execution: z.literal("not-performed"),
});
export type ApkSignatureResult = z.infer<typeof apkSignatureResultSchema>;

/** Counts disjoint unparsed suffixes; it does not classify their validity or meaning. */
export const apkSignatureUninterpretedBytes = (
  report: ApkSignatureResult,
): number => {
  let total = 0;
  for (const scheme of [
    report.schemes.v2,
    report.schemes.v3,
    report.schemes["v3.1"],
  ]) {
    total += scheme.uninterpreted_bytes;
    for (const signer of scheme.signers)
      total +=
        signer.uninterpreted_signed_data_bytes +
        signer.uninterpreted_signer_bytes +
        signer.digests.reduce(
          (n, record) => n + record.uninterpreted_bytes,
          0,
        ) +
        signer.signatures.reduce(
          (n, record) => n + record.uninterpreted_bytes,
          0,
        );
  }
  return total;
};

export const APK_SIGNATURE_LIMITATIONS: readonly string[] = [
  "Static structural inspection only. No Android code executes, no device or adb is involved, and odex/vdex/oat/cdex are not read.",
  "No signature is verified: signer, rotation-lineage and source-stamp signatures are NOT cryptographically checked, and certificate chains, revocation and authenticity are NOT evaluated. Certificates and lineages are what the APK declares.",
  "matches_apk and self_consistent only show that the declared content digest equals the digest of the current bytes. This is not a signature verification: anyone who changes the bytes can recompute the digest and write it into the signed data. SHA-256 identifies the exact bytes, not the producer.",
  "v1 signers are what each signature block's PKCS#7 SignedData declares: its signatures, the .SF and MANIFEST.MF digests and entry coverage are NOT verified.",
  "Not read: v4 .apk.idsig, verity digests (matches_apk null), and the v1 X-Android-APK-Signed marker, so v1_only cannot distinguish a v1-only APK from one whose v2/v3 block was removed.",
];

/** A block-scheme signer's declared rotation lineage, oldest certificate first. */
export type ApkPostureLineage =
  | { readonly kind: "absent" }
  | {
      readonly kind: "decoded";
      /** Per node, its certificate fingerprint; `null` when unknown. */
      readonly fingerprints: readonly (string | null)[];
    }
  | { readonly kind: "undecoded" };

/** One block-scheme signer as the posture derivation sees it. */
export interface ApkPostureSigner {
  /** `null` for a signer that carries no certificate (identity unknown). */
  readonly fingerprint: string | null;
  readonly lineage: ApkPostureLineage;
}

export type ApkBlockScheme = "v2" | "v3" | "v3.1";

/** Inputs to the pure posture derivation (scheme presence + agreement facts). */
export interface ApkPostureInput {
  readonly v1Present: boolean;
  readonly v2Present: boolean;
  readonly v3Present: boolean;
  readonly v31Present: boolean;
  readonly sourceStampPresent: boolean;
  /** Per present block scheme, lowest first, its signers. */
  readonly blockSchemes: readonly {
    readonly scheme: ApkBlockScheme;
    readonly signers: readonly ApkPostureSigner[];
  }[];
  /** Per v1 signer, the certificate its SignerInfo names; `null` when unknown. */
  readonly v1SignerFingerprints: readonly (string | null)[];
  readonly selfConsistent: boolean | null;
}

/** The posture plus why a derived fact stayed unknown, where it is not self-evident. */
export interface ApkPostureDerivation {
  readonly posture: ApkSignatureResult["posture"];
  readonly notes: readonly string[];
}

const setKey = (fingerprints: readonly string[]): string =>
  [...new Set(fingerprints)].sort().join(",");

/** Unknown signer identity or an undecoded lineage can hide the answer. */
const signerChangeDeclared = (
  signerSetsDiffer: boolean | null,
  signers: ReadonlySet<string>,
  lineage: ReadonlySet<string>,
  lineageUnknown: boolean,
): boolean | null => {
  if (signerSetsDiffer === null) return null;
  if (!signerSetsDiffer || signers.size <= 1) return false;
  if ([...signers].every((fp) => lineage.has(fp))) return true;
  return lineageUnknown ? null : false;
};

type Expected =
  | { readonly ok: true; readonly fingerprint: string | null }
  | { readonly ok: false; readonly reason: string };

/**
 * The certificate v1 is expected to carry for one signer of the lowest block
 * scheme. A v3/v3.1 signer that declares a lineage rotated away from the key
 * v1 (and v2) keep, so apksig requires the v1 signer to be the lineage's first
 * node; without a lineage it requires the v3 signer itself.
 */
const expectedV1Certificate = (
  scheme: ApkBlockScheme,
  signer: ApkPostureSigner,
): Expected => {
  if (
    signer.fingerprint === null ||
    scheme === "v2" ||
    signer.lineage.kind === "absent"
  )
    return { ok: true, fingerprint: signer.fingerprint };
  if (signer.lineage.kind === "undecoded")
    return {
      ok: false,
      reason: `the ${scheme} signer's declared rotation lineage could not be decoded`,
    };
  const origin = signer.lineage.fingerprints[0];
  return origin === undefined || origin === null
    ? {
        ok: false,
        reason: `the ${scheme} signer's declared rotation lineage names no readable original certificate`,
      }
    : { ok: true, fingerprint: origin };
};

/** v1 against what the lowest block scheme with signers expects; unknown stays unknown. */
const v1MatchesBlockSigners = (
  v1: readonly (string | null)[],
  lowest: ApkPostureInput["blockSchemes"][number] | undefined,
): { readonly match: boolean | null; readonly note: string | null } => {
  if (v1.length === 0 || lowest === undefined || lowest.signers.length === 0)
    return { match: null, note: null };
  const expected: (string | null)[] = [];
  for (const signer of lowest.signers) {
    const one = expectedV1Certificate(lowest.scheme, signer);
    if (!one.ok)
      return {
        match: null,
        note: `v1_signers_match_block_signers is null: ${one.reason}, so the original certificate v1 is expected to carry is unknown.`,
      };
    expected.push(one.fingerprint);
  }
  if (v1.includes(null) || expected.includes(null))
    return { match: null, note: null };
  return {
    match:
      setKey(v1 as readonly string[]) === setKey(expected as readonly string[]),
    note: null,
  };
};

/** Derive the conservative signing posture from observed and declared scheme facts. */
export const deriveApkPosture = (
  input: ApkPostureInput,
): ApkPostureDerivation => {
  const blockPresent = input.v2Present || input.v3Present || input.v31Present;
  const strongest = input.v31Present
    ? "v3.1"
    : input.v3Present
      ? "v3"
      : input.v2Present
        ? "v2"
        : input.v1Present
          ? "v1"
          : "none";
  const present = input.blockSchemes.filter(({ scheme }) =>
    scheme === "v2"
      ? input.v2Present
      : scheme === "v3"
        ? input.v3Present
        : input.v31Present,
  );
  const sets = present.map(({ signers }) =>
    signers.map(({ fingerprint }) => fingerprint),
  );
  // A signer without a certificate has unknown identity: agreement is unknown,
  // never assumed.
  const identityUnknown = sets.some((fps) => fps.includes(null));
  const known = sets.map((fps) =>
    fps.filter((fp): fp is string => fp !== null),
  );
  const union = new Set(known.flat());
  const signerSetsDiffer = identityUnknown
    ? null
    : new Set(known.map(setKey)).size > 1;
  const lineages = present.flatMap(({ signers }) =>
    signers.map(({ lineage }) => lineage),
  );
  const lineage = new Set(
    lineages.flatMap((l) =>
      l.kind === "decoded"
        ? l.fingerprints.filter((fp): fp is string => fp !== null)
        : [],
    ),
  );
  const v1Match = input.v1Present
    ? v1MatchesBlockSigners(input.v1SignerFingerprints, present[0])
    : { match: null, note: null };
  return {
    posture: {
      v1_only: input.v1Present && !blockPresent,
      schemes_agree_on_signer:
        union.size === 0 || signerSetsDiffer === null
          ? null
          : !signerSetsDiffer,
      signer_change_declared_by_rotation: signerChangeDeclared(
        signerSetsDiffer,
        union,
        lineage,
        lineages.some((l) => l.kind === "undecoded"),
      ),
      v1_signers_match_block_signers: v1Match.match,
      rotation_present: lineages.some((l) => l.kind !== "absent"),
      source_stamp_present: input.sourceStampPresent,
      strongest_scheme: strongest,
      self_consistent: input.selfConsistent,
    },
    notes: v1Match.note === null ? [] : [v1Match.note],
  };
};

/** The returned artifact identity must match the caller-selected local file. */
export const apkSignatureMatchesSubject = (
  artifact: ApkSignatureResult["artifact"],
  subject: EvidenceSubjectTarget,
): boolean =>
  artifact.sha256 === subject.sha256 &&
  artifact.path === subject.path &&
  (subject.format === "file" ||
    subject.format === "apk" ||
    subject.format === "zip");