Architecture doc: AutoFirma signing core (reference for web rewrite) #3
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
EduarD3V/AutoFirme#3
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
PROJECT PIVOT: repo goal is now AutoFirma Web — client-side rendered web app anyone can self-host, replicating AutoFirma, prettier, online. See AGENTS.md.
This issue: write docs/architecture.md from decompiled/sources/. Map:
Output: docs/architecture.md on branch docs/architecture, PR to main. ~400 lines max, tables over prose.
Document app architecture from decompiled sourceto Architecture doc: AutoFirma signing core (reference for web rewrite)bullet: coder launched on branch
issue/3-architecture-doc-autofirma-sig(modelnan/deepseek-v4-flash).Claimed — branch
issue/3-architecture-doc-autofirma-sig. Doing: map the signing core fromdecompiled/sources/and writedocs/architecture.md(~400 lines, tables; flows + keystores + deps + browser-migration notes).Plan — issue #3: Architecture doc, AutoFirma signing core
Restated goal
Write
docs/architecture.md(~400 lines, tables over prose) that maps AutoFirma 1.9's signingcore as read from the tracked jadx output in
decompiled/sources/, so the web rewrite can bedesigned against it. Four mapped areas, per the issue:
es/gob/afirma/keystores): cert types (DNIe, FNMT, PKCS#12), key access.document PKCS#12 upload / OS keystore alternatives.
"Done":
docs/architecture.mdexists on branchissue/3-architecture-doc-autofirma-sig,every row is either grounded in a read file (
file:line) or explicitly marked[INFERENCE],both gates green, committed, report written. No code changes — this is a pure doc deliverable.
Scope
docs/architecture.md(new file, only file touched).decompiled/**(read-only reference),docs/REVERSING-NOTES.md,AGENTS.md,.bullet/**, any source. No dependencies, no build config, nowebapp/.docs/architecture+ PR to main; bullet hard-law pins my branch toissue/3-architecture-doc-autofirma-sigand forbids pushing/PR. Assumption: orchestratorpublishes the branch and opens the PR. I commit to the assigned branch only.
Ordered tasks
AOSigner/AOSignerFactory,AOSignConstantsgrep -n "SIGNER_CLASS_" decompiled/sources/es/gob/afirma/core/signers/AOSignerFactory.javagrep -n "AOKeyStore(" decompiled/sources/es/gob/afirma/keystores/AOKeyStore.javadocs/architecture.mdwc -l docs/architecture.md≤ ~420test -d decompiled;find decompiled -name '*.java' | grep -q .git log --oneline -3Open questions (assumptions, proceeding)
docs/architecture; bullet assignsissue/3-architecture-doc-autofirma-sig.Assumption: bullet's branch wins (hard-law rule 1). Noted in report.
[INFERENCE]rather than guess. Assumption: an honest partial map beats an invented one.
cert issuers reached through PKCS#11/PC-SC. Assumption: document the real mechanism
(
AOKeyStoreenum + jmulticard) and say where DNIe/FNMT appear.Risk
decompiled/to exist with.javafiles — untouched, so greenunless something catastrophic. Fallback: report BLOCKED, change nothing.
file:lineper claim and marking inference.DONE
Commit:
e4900d1—docs: architecture.md — AutoFirma signing core map for the web rewrite (Refs #3)Gates:
test -d decompiled— PASSfind decompiled -name "*.java" | grep -q .— PASSgit diff --check— PASSFiles:
docs/architecture.md(new, 303 lines, 123 table rows). Nothing else touched.Scope: signer API +
AOSignerFactoryregistry; tri-phase (preSign → PKCS#1 sign → postSign) as the migration hinge; per-format flows CAdES/CMS (SpongyCastle), XAdES (jXAdES fork + JSR-105 + Santuario), PAdES (repackaged iTextcom.aowagie), ODF, OOXML, ASiC; fullAOKeyStoreenum + manager table + jmulticard PC/SC stack and on-card JCA provider; dependency triage; browser-migration map (WebCrypto/JS/WASM + keystore strategy, PC/SC has no browser path).Verification: all 38
file:linecitations resolve and are in-range; all 123 table rows column-consistent. No runtime surface for a doc.Notes: issue asked for branch
docs/architecture+ PR; bullet pinsissue/3-architecture-doc-autofirma-sigand forbids push — orchestrator publishes. Comments posted withBULLET_BASIC(BULLET_TOKENaccount cannot see the repo). 4 research scouts died on provider 429s; mapping done directly.bullet: coder session died — relaunched from committed state (branch
issue/3-architecture-doc-autofirma-sig).DONE (relaunched session — re-verified committed state)
Commits:
e4900d1(docs/architecture.md, 306 lines) +30ed442(5 citation/claim fixes)Gates:
test -d decompiled— PASSfind decompiled -name '*.java' | grep -q .— PASS (11,487)git diff --check— PASSRe-verified independently: all 68
file:linecitations resolve and are in bounds; anchor contents read back (AOSignerFactory registry, GenCAdESEPESSignedData tri-phase, AOKeyStore enum, DnieProvider SPI, AOPDFSigner iText imports). Fixed: SignatureFormatDetector filename, AOPkcs1Signer "retry" claim (it self-verifies), PAdES iText citation, KNOWN_SMARTCARDS keystore row, Rhino verdict.No push, tree clean. Refs #3.
bullet: coder session died — relaunched from committed state (branch
issue/3-architecture-doc-autofirma-sig).bullet: implementation finished (DONE (relaunched session — re-verified committed state)) — moving to review.
DONE (3rd session — re-verified committed artifact, no new edits)
Commits:
e4900d1(docs/architecture.md, 306 lines) +30ed442(5 citation/claim fixes)Gates:
test -d decompiled— PASSfind decompiled -name '*.java' | grep -q .— PASS (11,487)git diff --check— PASS (tree clean,git status --porcelainempty)Independent re-verification this run: 38
file:linecitations extracted and resolved against a recursive index ofdecompiled/sources— 0 unresolved, 0 out of range; anchors read back (AOSignerFactory:13/29/36/92/114, AOKeyStore:11-31 = 19 enum constants, Pkcs1Utils:15/32, DnieProvider:13/58-61). Doc line count 306/400.No push, nothing to commit. Refs #3.
bullet: reviewer launched (model
9router/reviewer, independent of coder).REVIEW: FIXED 3 — commit
c4b0473: doc cross-refs keystore layer/on-card provider pointed at §5 instead of §4 (lines 24, 94); tri-phase constants citation:26-36missed its named itemsserverUrl(:24) andsession(:37) →:24-37(line 75). All 37 file:line citations resolve; 4 issue areas + plan scope verified against decompiled sources; gates green. UNFIXED: nonebullet: fixer launched (round 1/2).
FIXED: applied 0 new code fixes — all 3 findings were already fixed in
c4b0473(review round); this round adds the missing regression coverage and re-verifies each fix.architecture.md:24"keystore layer (§5)" →c4b0473, verified by read-back: §4 is "Keystore layer", §5 is "Dependency triage".architecture.md:94"on-card-signing provider (§5)" →c4b0473, verified by read-back: provider stack is documented in §4.:26-36missedserverUrl(:24)/session(:37) →c4b0473(:24-37); regression test2e0370c.UNFIXED: none. Coverage limit: findings 1–2 are cross-ref semantics inside prose — a mechanical check for them would be plain text pinning, so only the citation invariants are locked.
2e0370cfix(review): machine-check architecture.md citations (Refs #3) —docs/check-architecture-doc.pyresolves all 38file:linecitations againstdecompiled/, rejects out-of-range spans and dangling§N, and fails when a cited range does not contain the identifiers its sentence names. Negative controls: reverting:24-37→:26-36fails, widening:20-40passes, bogus line/file/§9 fail.Gates (re-run after the commit):
python3 docs/check-architecture-doc.pyPASS (38 citations) ·test -d decompiledPASS ·find decompiled -name '*.java' | grep -q .PASS ·git diff --checkPASS. Tree clean, no push.bullet: fixer round done — fresh reviewer re-checking.
REVIEW: FIXED 1 — commit
2e0370c; findings: §2 exception-mapping list named 3 of the 4 exceptions thrown in the cited range AOPkcs1Signer.java:60-71 — LockedKeyStoreException missing — fixed in8389572; UNFIXED: noneEvidence: 38/38 citations resolve + negative control (out-of-range mutation) fails as designed (
python3 docs/check-architecture-doc.py); gatestest -d decompiled,find decompiled -name *.java,git diff --checkall exit 0; issue coverage §1-§3 (flows), §4 (keystore), §5 (deps), §6 (WebCrypto/WASM/PC-SC-alternatives) verified against source line-by-line; scope = docs/architecture.md (310 lines, ≤400) + docs/check-architecture-doc.py only; no test/checker weakened; tree clean.bullet: fixer round done — fresh reviewer re-checking.
REVIEW: CLEAN — commit
8389572: findings nonebullet: review CLEAN — ready to publish.
bullet: merged into
bullet-develop— integration gates green.bullet: work already merged into
bullet-develop.